# 线上访问整站（手机 / 另一台电脑都能开）

学习站、讲义 HTML、总目录打成**一份静态站**。合入 `main` 后 GitHub Actions 自动构建 `_site/`，并上传到 **Cloudflare Pages**（仓库可保持私有）。之后改文档、加解析页，合并就能在同一个网址打开，不必再起 7200/7300/7400。

**推荐地址（Cloudflare，私有仓库也能公开看）：**

**https://kaiyuan-xiangmu-jiexi-zixi.pages.dev/**

（第一次部署若名字被占用，Cloudflare 会在后面加几个字符，以 Actions 日志里的 URL 为准。）

备用：GitHub Pages `https://mikayiyang.github.io/kaiyuan-xiangmu-jiexi-zixi/`（免费账号需要仓库 Public）。

根路径会跳到总目录。交互学习站收在同一域名下：

| 原来的本地端口 | 线上路径 |
|---|---|
| `:7300` Claude Code v1 | `/learn/claude-v1/` |
| `:7301` Claude Code v2 | `/learn/claude-v2/` |
| `:7200` OpenManus × Suna | `/learn/manus/` |
| `:7200/build-guide.html` | `/learn/manus/build-guide.html` |
| `:7397` 从零构建指南站 | `/learn/agent-guide/` |
| `:7380` DeepSeek Harness（若该学习站已合入） | `/learn/dsh/` |
| `:7400/….html` 讲义（含 Easel） | 站点根上的同名文件 |

源码里的总目录仍写 `127.0.0.1` 端口，方便本机多进程预览；**只有构建产物 `_site/`** 会把这些地址改成相对路径。不要手改总目录里 `AUTO-CATALOG` 区间。

构建在 GitHub Actions 完成。默认把打好的 `_site/` 推到 **`site` 分支**；Cloudflare 只负责托管，不要让它从 `main` 编译（那套环境不好装 Python + 四个 Vite 站）。

---

## 方案怎么选

| 方案 | 域名 | 仓库可否保持私有 | 要不要你的服务器 |
|---|---|---|---|
| **A. Cloudflare Pages 接 `site` 分支（推荐）** | `*.pages.dev` | 可以，站点本身公开可看 | 不用 |
| **A2. Wrangler 直传** | 同上 | 可以 | 不用；Token 必须能管 Pages |
| **B. GitHub Pages** | `mikayiyang.github.io/kaiyuan-xiangmu-jiexi-zixi/` | 免费账号需要 **Public** | 不用 |
| **C. 你的轻量服务器** | 服务器 IP 或你自己的域名 | 可以 | 要用，拷 `_site/` |

`github.io` 不能指到你的机器，也不能指到 Cloudflare。互相独立。

---

## A. Cloudflare Pages 接 Git（稳妥，不依赖 API Token）

Wrangler 直传曾出现 **error 7003**（Account ID 长度对、密钥也进了 Actions，但 Cloudflare 仍说路由不到）。这通常是 **Token 没有 Pages 权限，或 Token 和 Account 不是同一个账号**，不是 ID 抄错。

所以流水线改成：合入 `main` 后把静态站推到 **`site` 分支**。你只要在 Cloudflare 里接一次 Git。

### 1. 先合 PR，让 Actions 推 `site` 分支

Actions → **Deploy site** 变绿后，仓库里应出现分支 `site`：

https://github.com/mikayiyang/kaiyuan-xiangmu-jiexi-zixi/tree/site

### 2. 在 Cloudflare 接这个分支

1. 打开 [Workers 和 Pages](https://dash.cloudflare.com/?to=/:account/workers-and-pages)
2. **Create** → **Pages** → **Import an existing Git repository**
3. 授权 GitHub，选仓库 `kaiyuan-xiangmu-jiexi-zixi`（私有也可以）
4. 设置：
   - Production branch：**`site`**（不要选 `main`）
   - Framework preset：**None**
   - Build command：**留空**
   - Build output directory：**`/`**
5. Save / Deploy

之后每次合入 `main`，Actions 会覆盖 `site`，Cloudflare 自动上线。地址仍是 `*.pages.dev`。

---

## A2. Wrangler 直传（可选）

若 Token 权限是对的，同一条流水线仍会尝试 `wrangler pages deploy`。失败不会挡住 `site` 分支。

做 Token 时请用模板 **Edit Cloudflare Workers**（自带 Pages），不要只用自定义里某一行：

1. [Account API tokens](https://dash.cloudflare.com/?to=/:account/api-tokens) → Create Token → **Edit Cloudflare Workers** → Use template
2. Account Resources 选**同一个**账号
3. 抄 Workers 和 Pages 总览右侧的 **Account ID**（不要抄某个域名下面的 Zone ID）
4. 仓库 [Repository secrets](https://github.com/mikayiyang/kaiyuan-xiangmu-jiexi-zixi/settings/secrets/actions)：
   - `CLOUDFLARE_API_TOKEN`
   - `CLOUDFLARE_ACCOUNT_ID`

### 本机手动传一次（可选）

```bash
export CLOUDFLARE_API_TOKEN='…'
export CLOUDFLARE_ACCOUNT_ID='…'
./scripts/deploy-cloudflare.sh
```

---

## B. GitHub Pages（可选备用，当前流水线不推）

这个仓库现在是**私有**的。GitHub 免费账号**不会给私有仓库做公开 Pages**。当前 Actions 推的是 **`site` 分支给 Cloudflare**，不是 GitHub Pages 的 `gh-pages`。

若以后仓库改成 Public、要用 github.io：

1. GitHub 仓库 → **Settings → General → Danger Zone → Change repository visibility → Public**。
2. 用 `python3 scripts/build-site.py` 打出 `_site/`，把内容放到 Pages 要求的分支 / Actions 官方 Pages 工作流。
3. **Settings → Pages** 按 GitHub 文档打开。

私有仓库若有 GitHub Pro / Team，Pages 只对有仓库权限的人可见。日常学习请用上面的 `pages.dev`。

---

## C. 用你的轻量服务器镜像同一份站点

适合已经有公网 IP / 自己的域名。和 Cloudflare 互不影响。

```bash
python3 scripts/build-site.py
rsync -a --delete _site/ user@你的服务器:/var/www/learn/
```

Nginx 示例：

```nginx
server {
    listen 80;
    server_name _;
    root /var/www/learn;
    index 总目录.html index.html;
    location / {
        try_files $uri $uri/ /总目录.html;
    }
}
```

中文文件名要保证服务器 locale 是 UTF-8。

---

## 本地预览「和线上同一份」

```bash
python3 scripts/build-site.py          # 打出 _site/
python3 -m http.server 7400 --directory _site --bind 127.0.0.1
# 打开 http://127.0.0.1:7400/总目录.html
```

`./start-html-previews.sh` 默认会组装 `_site/`，把 **7400** 指到这份统一站点。跳过组装：`UNIFIED=0 ./start-html-previews.sh`。

---

## 以后更新怎么出现在线上

和平时一样改 Markdown / 学习站 → `python3 build-html.py`（若动了被收录的 md）→ `python3 update-catalog.py` → commit 并**合入 `main`**。Actions 会重建 `_site` 并上传 Cloudflare。不用再起 7200/7300 那些端口才能看。