From e5e96324603a0923df2e1253d4d56cbd68205294 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Fri, 31 Jul 2026 22:02:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20session-environment-guide=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E4=B8=BA=E5=88=86=E5=B1=82CI/CD=E6=B5=81=E7=A8=8B(NAS?= =?UTF-8?q?=E8=87=AA=E5=8A=A8+VPS=20dispatch+agent=20PAT)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step2 改 promote --target nas(CI自动为主,手动应急);§8 改已建成分层(双workflow隔离+两种approve+PAT osxkeychain sanguo-gitea-ci)。原写同时推NAS+VPS/审批gate过时。 --- docs/session-environment-guide.md | 34 ++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/session-environment-guide.md b/docs/session-environment-guide.md index 0bc6baf..8918f9b 100644 --- a/docs/session-environment-guide.md +++ b/docs/session-environment-guide.md @@ -47,13 +47,17 @@ pytest tests/<你的模块>/ -q ``` **预期**：全绿。Mac 用 fixture，不需要真实数据。 -### Step 2 — 部署 NAS test + VPS prod（一条命令同时推） +### Step 2 — 部署 NAS test（CI/CD 自动 / 手动应急） +> **默认走 CI/CD 自动**：`git push origin master` → 自动 `test → nas-deploy(推 NAS 后端+前端 dist) → nas-verify(秒级 gate)`。nas-verify 绿 = NAS test 已部署验证。**VPS 不在这里推**（见 Step 4）。详见 §8。 + +手动（应急 / CI 没跑 / Mac 睡眠）： ```bash -bash scripts/nas_sync/promote.sh --module sanguo_<你的模块> +bash scripts/nas_sync/promote.sh --target nas --module sanguo_<你的模块> # 单模块只推 NAS +bash scripts/nas_sync/promote.sh --target nas # 全量只推 NAS ``` -- 单模块补推用 `--module`；**改了多个模块或根文件**（pyproject/pytest.ini/requirements/run_web.py）用全量 `bash scripts/nas_sync/promote.sh`。 -- promote.sh 内部：Mac→NAS(rsync，LAN 快) + Mac→VPS(scp)。**数据铁律双防护**，绝不会推 `data/`。 +- promote.sh 支持 `--target nas|vps|all`（默认 all）。NAS 走 rsync（LAN 快），VPS 走 scp。**数据铁律双防护**，绝不推 `data/`。 +- 前端 dist 不在 promote.sh（gitignore）；CI 自动 `npm build` + rsync dist。手动推前端见运维。 ### Step 3 — NAS 冒烟（数据层/读取层改动必跑） @@ -129,17 +133,23 @@ VPS 是**一次性任务**模型（回测 runner + 采集 schtask），**没有 --- -## 8. CI/CD（自动化，建设中） +## 8. CI/CD（已建成，分层：NAS 自动 + VPS dispatch） -目标形态（Gitea Actions，NAS 1.26.2 已支持）： +Gitea 不支持 environment approval gate，故用**双 workflow** 隔离 NAS test / VPS prod： ``` -push master → 自动 NAS 单测+冒烟(job_nas_test) → 通过 → 审批后推 VPS+冒烟(job_vps) +push master → ci-cd.yml 自动: test(pytest) → nas-deploy(推NAS后端+前端dist+restart容器) → nas-verify(login+strategy/list+dbbardata 秒级 gate) + ↓ nas-verify 全绿 = NAS test 已部署+验证 + ⏸️ VPS 不自动推，停下等触发 +推 VPS(nas-verify 绿后，触发 vps-deploy.yml，两种 approve): + 人工 = Gitea UI → Actions → vps-deploy.yml → Run workflow(填 sha) + agent = curl -H "Authorization: token $PAT" POST .../dispatches body {"ref":"master","inputs":{"sha":""}} + ↓ checkout 你传的 SHA(= NAS 验证过的) → promote --target vps → verify_unified_e2e ``` -- **P2（NAS CI）**：push 自动跑 pytest + smoke_e2e.py。 -- **P3（VPS CD）**：NAS 通过 → 人工审批 gate（prod 安全）→ 自动 scp 推 VPS + verify_unified_e2e.py。 -- **建成前**：按本手册 §3 手动走（5 步）。 - -建成状态见运维 session 更新。 +- **NAS 自动**：push 即触发 ci-cd.yml；nas-verify 是秒级 gate（API 健康 + 数据可读）。runner 是 Mac（睡眠时 CI 不跑，手动 `promote --target nas` 应急）。 +- **VPS 严格版本**：vps-deploy.yml 接收 `sha` input，checkout 该 commit（= nas-verify 验证过的），绝不部署未验证代码。 +- **agent approve 的 PAT**：osxkeychain 存了 `sanguo-gitea-ci`（scoped `write:repository`）。取用：`token=$(security find-generic-password -s sanguo-gitea-ci -a agent -w)`，再 `curl -H "Authorization: token $token" ...`。⚠️ MCP claude_dev token 无 write 权限（dispatch 会 403）。 +- **前端 dist**：ci-cd.yml 的 nas-deploy 自动 `npm ci + build + rsync dist`（不 commit dist、不进 promote.sh）。 +- workflow 文件：`.gitea/workflows/ci-cd.yml`(push→NAS) + `vps-deploy.yml`(dispatch→VPS)。 ---