# x.yinledou.com 部署与同步手册

## 1. 目标与单一入口

- 生产入口固定为 `https://x.yinledou.com/`。
- 首页只负责项目分流。当前主项目为“跨境电商商业可行性追踪”和“商业机会向量验证”；不得在总览混排国家、平台、书库或其他项目内容。
- 香港与北京是同一发布包的镜像节点，不得按访问地域注入、删改或替换页面内容。两端都必须从 `outputs/x-hub/` 同步，并保留相同的 `release-manifest.json`。
- 每个项目在一级项目页内，再通过二级标签进入国家、商业模型、方法论或档案。完整原始报告放在 `artifacts/` 并以独立页面打开。
- Nowledge Mem 是长期记忆单一事实源：每次成功部署必须更新记忆，并把更新后的主页面、部署手册和关键报告添加到 Library。

## 2. 源文件和构建结果

| 用途 | 固定路径 |
| --- | --- |
| x 站点构建器 | `/Volumes/OS2App/AiColding/yinledou/work/build_x_hub.py` |
| x 站点输出目录 | `/Volumes/OS2App/AiColding/yinledou/outputs/x-hub/` |
| 跨境电商唯一产物 | `/Users/elvis/Documents/Codex/2026-05-31/6-4-02-00-08-00/CBEC_Business_Hub.html` |
| 商业机会研究输出 | `/Users/elvis/Documents/Codex/2026-08-12/referenced-chatgpt-conversation-this-is-an/outputs/` |
| 双云部署入口 | `/Volumes/OS2App/AiColding/yinledou/scripts/deploy_yinledou_dual_cloud.py` |
| Nginx 配置 | `/Volumes/OS2App/AiColding/yinledou/deploy/nginx-yinledou.conf` |

构建器会复制跨境电商主 HTML、机会研究完整报告、100 本书语料和理论审计，并生成唯一的 `index.html`。绝不把“100 本公开资料交叉研究”表述成“通读 100 本”；本地可访问原书/章节只有 3 份，另有 9 份摘要。

## 3. 标准发布流程

1. 先检查两个研究源文件存在且更新时间合理；禁止用空白或旧临时文件覆盖线上版本。
2. 构建 x 站点：`python3 work/build_x_hub.py`。
3. 本地静态检查：确认 `outputs/x-hub/index.html`、两个 `artifacts/` 子目录和本手册均存在。
4. 远端只读预检：确认北京节点 `49.232.229.68` 的 `yinledou-web` 容器、`/opt/yinledou/site/x` 和证书状态；发布前先压缩备份现有 `/opt/yinledou/site/x` 与 `/opt/yinledou/nginx/default.conf`。
5. 使用双云脚本同步：它先构建主站和 x 发布包，再把同一个 x 输出目录同步到香港 FTP `/wwwroot/x` 和北京 `/opt/yinledou/site/x`，并重启 Nginx 容器。
6. 发布后分别下载香港与北京的 `release-manifest.json`，比较文件清单与哈希完全一致；再验证 HTTPS、页面标题、两个项目入口、跨境电商附件、机会研究附件与手机窄屏布局。
7. 更新 Nowledge Mem：写入本次版本、构建时间、来源文件、上线验证证据和未解决风险；将 `index.html`、本手册与关键报告添加到 Library。

## 4. 凭据与安全边界

- 香港 FTP 仅从环境变量或 `launchctl` 获取：`YLD_FTP_HOST`、`YLD_FTP_USER`、`YLD_FTP_PASS`。
- Bitwarden 桌面端解锁不会自动授权 `bw` CLI。需要读取 FTP、面板或证书明文时，用户必须在同一终端执行 `export BW_SESSION="$(bw unlock --raw)"`；随后 agent 仅在内存中读取并使用所需字段，绝不打印、落盘或写入 Nowledge Mem。SSH 私钥场景走 `bw-agent`，不需要也不应执行 `bw unlock`。
- 北京节点默认 `ubuntu@49.232.229.68`，私钥只从 `YLD_TENCENT_KEY` 或既有受保护路径读取；不得把密码、私钥、哈希或面板令牌写进 HTML、日志或 Nowledge Mem。
- 未完成远端备份、构建检查或域名验证时，不得声称已部署。

## 5. TLS 证书续签

- 证书文件在北京 `/opt/yinledou/certs/fullchain.pem` 和 `privkey.pem`，由容器只读挂载。
- 在到期前 30 天检查：`openssl x509 -in /opt/yinledou/certs/fullchain.pem -noout -dates`。
- HTTP-01 验证钩子为 `scripts/letsencrypt_ftp_auth.py` 和 `scripts/letsencrypt_ftp_cleanup.py`；它们使用临时环境变量上传/清理验证文件，不能打印凭据。
- 续签后需要同时更新香港 Easypanel 的 SSL 设置和北京证书目录，再重启 `yinledou-web`，最后用不跳过证书校验的 HTTPS 检查域名。
- 当前或任何一次发现证书过期时，先修证书再对外宣布链接可用。

## 6. 验收命令与判定

```bash
curl -fsSI https://x.yinledou.com/
curl -fsS https://x.yinledou.com/ | rg '财绅研究工作台|跨境电商|商业机会向量验证'
curl -fsSI https://x.yinledou.com/artifacts/cbec-business/CBEC_Business_Hub.html
curl -fsSI https://x.yinledou.com/artifacts/opportunity-vector-validation/opportunity-vector-validation-final-research-report.html
curl --resolve x.yinledou.com:443:49.232.229.68 -fsSI https://x.yinledou.com/
```

成功标准：所有命令 HTTP 200、TLS 校验正常、首页可切换两个一级项目、跨境电商国家切换只显示所选国家内容、机会向量页明确展示“100 本公开资料研究 / 3 份本地原书或章节 / 9 份摘要”的边界。

## 7. 回退与故障处理

- 发布前备份目录以 UTC 时间命名，保存至北京 `/opt/yinledou/backups/`；香港同步失败不得触碰北京已验证版本。
- 若新页面异常，恢复最近备份到 `/opt/yinledou/site/x`，恢复 Nginx 配置，重启容器并重新执行第 6 节验收。
- 若香港仍显示旧页，先检查 FTP 上传清单与主机缓存；若北京正常而公网异常，分别检查 DNS 线路、443 安全组与证书链。
- 只报告已由命令或 HTTP 响应验证的状态。未完成的一侧必须明确写为“待修复”，不能称为双云成功。