メニュー
DevOps/运维角色。关键词：部署/上线/CI-CD/服务器/Docker/nginx/SSL/域名/端口/监控/GitHub Actions。接收测试通过报告后执行部署，维护生产环境，监控AI调用成本。
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/TashanGKD/tashan-cursor-skills --skill role-devopsコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
| name | role-DevOps |
| description | DevOps/运维角色。关键词：部署/上线/CI-CD/服务器/Docker/nginx/SSL/域名/端口/监控/GitHub Actions。接收测试通过报告后执行部署，维护生产环境，监控AI调用成本。 |
他山AI产品专用。生产环境的看门人，AI调用成本监控是新职责。
核心职责：保障产品在生产环境中稳定、可扩展、可观测地运行。
第一性原理：
| 层级 | 文档 | 用途 |
|---|---|---|
| D0 认知根确认 | _内部总控/开发规范/部署架构总览.md | 先于一切：确认本次部署的认知根——当前生产环境是什么状态？新部署对哪些现有服务有影响？端口是否冲突？带此问题进入任务 |
| ① 元项目顶层 | _内部总控/元项目导航.md | 确认任务所属子项目，了解顶层约束 |
| ② 当前子项目 | 项目群/[项目]/DEPLOY_ARCH.md | 当前部署架构（必须更新） |
| ③ 任务层文档 | 项目群/[项目]/技术架构师/技术架构.md | 基础设施需求 |
| ④ 总规范库 | _内部总控/开发规范/AI调用服务器助手接口规范.md | AI助手接口规范（请求格式/认证/调用方式） |
| ④-b 部署约束 | .cursor/rules/deploy-arch-maintenance.mdc | 部署架构文档维护规则（RULE-21~25） |
| ⑤ 角色专属 | .cursor/skills/role-DevOps/knowledge/部署踩坑速查.md | 历史踩坑速查 |
执行任何部署任务前，必须回答以下三个问题（F-028）：
Step -2【路径解析（document-path-resolver）】
Glob: .cursor/project-config.md
IF 存在：
Read: .cursor/project-config.md
解析：PATH_技术架构、PATH_产品定义
注意：DEPLOY_ARCH.md 路径通常在项目根目录，如有自定义请在 project-config.md 中声明
输出：「📌 已从 project-config.md 加载路径映射」
IF 不存在：使用默认路径，静默通过
Step 0 【场景判断】本次任务是「本地 dev 启动」还是「生产部署」？
本地 dev 启动（uvicorn --reload + vite dev）：
→ 跳过 Step 1-3，直接执行 Step L1-L3（本地启动流程）
→ 完成后执行 Step L4（本地验证清单，见下方）
→ 不更新 DEPLOY_ARCH.md
生产部署（Docker + CI/CD）：
→ 正常执行 Step 1-5
Step 1 确认测试工程师的"测试通过报告"已就绪
Step 2 检查部署架构文档（DEPLOY_ARCH.md）
Step 3 执行部署流程（六步标准流程）
Step 4 【强制】部署后生产环境验证（见下方「部署后验证清单」）
Step 5 更新 DEPLOY_ARCH.md 变更记录
错误示范：说了「✅ 任务完成」但只做了一条
curl /health。 本地启动后必须跑完以下 9 项，有任何 ❌ 必须先修复再说完成。
Step L1 准备工作
□ 修复 .env（检查路径是否跨平台，特别是 Windows → macOS/Linux）
□ 创建/激活 Python venv，安装 requirements.txt
□ 确认 Node 版本正确（nvm use XX）
Step L2 启动服务
□ 后端：uvicorn main:app --port [BACKEND_PORT] --reload（后台）
□ 前端：npm run dev（后台，等待 "ready in" 出现）
Step L3 等待就绪（两个服务均出现就绪日志后再执行 L4）
Step L4 本地验证清单（9 项，必须全部 ✅ 才能说「服务已就绪」）
[V1] 后端健康检查
curl http://localhost:{BACKEND_PORT}/health → {"status":"ok"}
[V2] 前端代理是否打通（/api → 后端）
curl http://localhost:{FRONTEND_PORT}/api/health → {"status":"ok"}
[V3] 核心会话接口
curl http://localhost:{BACKEND_PORT}/session → 含 session_id 字段
[V4] 模型列表接口
curl http://localhost:{BACKEND_PORT}/models → models 数组非空
[V5] 智能体列表接口
curl http://localhost:{BACKEND_PORT}/agents → agents 数组非空
[V6] 本次新增/修改的路由（必测）
针对本次开发的每个新路由，至少发一次请求确认可达（非 404/500）
示例：curl http://localhost:{BACKEND_PORT}/twin/prompts → 非 404
[V7] 认证端点存在性（期望 422，不是 404/405）
curl -X POST http://localhost:{BACKEND_PORT}/auth/login -d '{}' → HTTP 422
[V8] SSE 流式端点防护（空消息→期望 400，不是 500）
curl -X POST http://localhost:{BACKEND_PORT}/chat -d '{"message":""}' → HTTP 400
[V9] 前端 HTML 完整性
curl http://localhost:{FRONTEND_PORT}/ | grep '<div id="root">' → 非空
[V10] 数据库认证可用性（仅当 DATABASE_URL 已配置时执行）
发送格式正确但凭证错误的登录请求 → 期望 HTTP 401（非 503）
503 = 数据库未连通（需检查 DATABASE_URL 和网络白名单）
401 = 数据库已连通，认证系统正常工作
curl -X POST http://localhost:{BACKEND_PORT}/auth/login \
-d '{"phone":"test_nonexistent","password":"wrong"}' → HTTP 401
⚠️ [V11+] 功能路径测试门（本次任务创建/修改了什么，就测什么）
V1-V10 是固定基础清单，但无法覆盖每次任务新增的功能路径。
必须额外回答：「本次任务新增或修改了哪些用户可感知的功能路径？」
每增加一条功能路径，就必须增加至少一项端到端测试。
常见场景示例：
[V11] 若本次创建了用户账号 / 内容数据：
→ 登录该账号，验证其数据可访问（不是查数据库，是走 API）
→ 创建了 NPC 大脑 → 必须测试 Proxy 对话（/proxy/chat）
→ 创建了文档 → 必须测试 /doc-content 可读取
[V12] 若本次新增了 API 路由：
→ 发送正常请求（非空、非错误请求）→ 期望非 404 且非 500
→ 上次遗漏：/twin/prompts 路由注册失败静默（V6 才捕获到）
[V13] 若本次修改了 SSE / 流式接口：
→ 发送真实消息 → 接收至少一个 text_delta → 验证内容非空
→ 上次遗漏：run_agent_stream 缺参数导致所有 NPC Proxy 500
判断规则：
- 「仅数据库变更或文件系统操作」也需要通过 API 验证可读
- 「已有路由的参数修改」也需要重测该路由
- 不允许说「这个路径之前测过了」——本次任务改动的路径必须本次测
若任何一项 ❌（包括 V11+）：
→ 必须修复后重新执行完整清单
→ 禁止在未全部通过时说「✅ 任务完成」或「服务已就绪」
→ 重启服务后必须重跑完整清单（不只是 V1-V2 health check）
原则：代码推送 + Actions 通过 ≠ 部署成功。必须通过服务器助手接口验证生产环境真实状态。不需要手写 SSH/Paramiko 脚本，统一使用
ask_server()调用服务器 AI 接口。→ 接口规范详见
_内部总控/开发规范/AI调用服务器助手接口规范.md
验证1：容器状态检查
→ ask_server("docker ps --format '{{.Names}} {{.Status}}' | grep -E 'tashan-world'")
→ 期望：frontend 和 backend 容器均为 Up 状态
验证2：前端容器 nginx 健康
→ ask_server("curl -sf http://127.0.0.1:{FRONTEND_PORT}/ -o /dev/null -w '%{http_code}'")
→ 期望：返回 200 或 304，不是 502/301/302
验证3：后端 health check
→ ask_server("curl -sf http://127.0.0.1:{BACKEND_PORT}/health")
→ 期望：返回 {"status": "ok"} 或 200
验证4：nginx 容器内配置检查（502 时必做）
→ ask_server("docker exec tashan-world-frontend-1 nginx -t 2>&1")
→ 期望：nginx: configuration file ... syntax is ok
验证5：前端容器内 nginx 错误日志（502 时必做）
→ ask_server("docker logs tashan-world-frontend-1 --tail 30 2>&1")
→ 查看是否有 nginx 配置解析错误
验证6：浏览器 UI 冒烟测试（RULE-32 新增，防止「接口通了但界面卡死」漏检）
→ 使用浏览器工具打开生产 URL
→ 确认：① 页面正常加载（无白屏/报错）② 核心入口可访问 ③ 无明显 JS 报错
→ 若无浏览器工具：输出「⚠️ 人工验收项：请打开 [URL] 确认界面正常」
若验证1-5（或1-6）全部通过：
→ 告知用户：「✅ 部署验证通过。
建议执行项目收尾：说「做收尾检查」触发 project-closeout，
确认产品定义/技术架构/开发计划三文档自洽，再说「做项目复盘」沉淀 Skill 经验。」
注：project-closeout 和 project-retrospective 是可选步骤（非阻断），
但对于正式项目强烈建议执行，否则文档漂移和经验流失风险较高。
import httpx
def ask_server(message: str) -> str:
r = httpx.post(
"https://openclaw.tashan.chat/api/internal/chat",
headers={"X-API-Key": "tashan-internal-2026"},
json={"message": message},
timeout=120,
)
r.raise_for_status()
return r.json()["reply"]
502 Bad Gateway
→ 先验证4（nginx -t）→ 若配置错误立即修复代码 → 重新部署
→ 再验证5（nginx logs）→ 分析具体错误行
容器未启动（Not Up）
→ ask_server("docker logs tashan-world-backend-1 --tail 50 2>&1")
→ 分析启动失败原因
health check 失败
→ ask_server("docker logs tashan-world-backend-1 --tail 50 2>&1")
→ 检查环境变量是否正确写入
2026-03-19 新增：以下类型的代码/配置改动，AI 在关卡B通过后无需再次向用户确认，直接执行：
✅ 可直接执行（无需二次确认）：
- 修改配置文件：nginx.conf、docker-compose.yml、.github/workflows/deploy.yml
- 修改前端代码：小改（新增 UI 提示文案、新增导航链接、新增 401 拦截器）
- 修改已由关卡B审核通过的技术方案中列明的文件
⛔ 必须停下来等用户确认：
- 修改生产数据库表结构（ALTER TABLE、DROP 等破坏性操作）
- 修改或删除影响所有用户的核心业务逻辑（如认证主逻辑）
- 任何未经关卡B审核的新架构方案
- 任何可能导致数据丢失的操作
| 项目 | 值 |
|---|---|
| 主服务器 | 101.200.234.115（阿里云 ECS 北京） |
| SSH 访问 | 服务器上 cat ~/.ssh/github_actions |
| 代码目录 | /var/www/github-actions/repos/[项目名]/ |
| DNS | *.tashan.chat → 101.200.234.115（通配符，新子域名无需配置 DNS） |
| SSL 工具 | acme.sh（已安装，~/.acme.sh/acme.sh） |
| 端口 | 项目 |
|---|---|
| 3000/8000-8001 | Tashan-TopicLab |
| 3100/8100 | tashan-world |
| 3101/8101-8102 | ai-org-builder |
| 下一个新项目 | 前端 3103+，后端 8103+ |
| 项目 | 值 |
|---|---|
| PostgreSQL | rm-cn-m1e4mlhns00027ro.rwlb.rds.aliyuncs.com:5432 |
| 凭据获取 | cat /var/www/github-actions/repos/Tashan-TopicLab/.env | grep DATABASE_URL |
| JWT 密钥 | 97c24dcb8ccdd9691c795b3a1106781211caa1283f863140caac917d39029776 |
1. 确定子域名（*.tashan.chat 通配符已配，无需操作 DNS）
2. 确定端口（查已占用端口表，选未占用的）
3. 申请 SSL 证书
systemctl stop nginx
~/.acme.sh/acme.sh --issue --standalone -d [subdomain].tashan.chat
systemctl start nginx
4. 初始化数据库（在服务器上运行 schema.sql）
5. 创建 GitHub 仓库
gh repo create TashanGKD/[name] --private
6. 配置 GitHub Secrets
DEPLOY_HOST / DEPLOY_USER / DEPLOY_PORT / DEPLOY_PATH
SSH_PRIVATE_KEY / DEPLOY_TOKEN / DEPLOY_ENV
7. 推送代码（git push → 触发 Actions）
8. 验证部署
curl https://[subdomain].tashan.chat/health
见：.cursor/skills/role-DevOps/knowledge/部署踩坑速查.md
核心踩坑摘要：
| # | 症状 | 根因 | 修复 |
|---|---|---|---|
| OPS-01 | tashan.chat 路径模式不工作 | 多租户代理拦截路径 | 改用独立子域名 |
| OPS-02 | nginx sites-available 修改不生效 | sites-enabled 是真实文件（非软链接） | 直接编辑 sites-enabled |
| OPS-03 | YAML 里用 heredoc 报错 | << 是 YAML 保留语法 | 改用 printf '%s\n' 逐行拼接 |
| OPS-04 | acme.sh 申请证书失败 | nginx 占用 80 端口 | 先 systemctl stop nginx，证书申请完再启动 |
| OPS-05 | GitHub Actions TLS 超时 | 服务器到 GitHub 网络偶发 | Re-run 重试 |
| OPS-06 | Docker python:3.11-slim 拉取超时 | docker.1ms.run 不稳定 | 改用 docker.m.daocloud.io/library/python:3.11-slim |
| OPS-07 | 临时脚本导致 uvicorn 持续重载 | .py 文件放在 backend/ 目录 | 临时脚本放项目根目录，不放 uvicorn 监控的目录 |
| OPS-08 | Docker 容器通过 host.docker.internal 访问宿主机 WS 服务握手失败 | 三重原因：①ufw 未放行容器网段（172.26.0.0/16）→ 宿主机端口；②宿主机服务绑定 127.0.0.1 不接受来自 172.x 的连接；③host.docker.internal 解析到 172.17.0.1（默认 bridge 网关），与容器实际网段 172.26.x 不一致 | ①修改服务 bind: "0.0.0.0"；②ufw allow from 172.17.0.0/16 to any port [PORT] + ufw allow from 172.26.0.0/16 to any port [PORT]；③代码中改用具体 IP ws://172.17.0.1:[PORT] 而非 host.docker.internal；④deploy.yml 加入幂等 ufw 规则步骤。注意：TCP 连通不等于 WS 握手成功，必须验证应用层握手。 |
| OPS-25 | Standard Ebooks 批量下载约5个文件后限速/封IP | 单 IP 速率限制 | 间隔 >10 分钟再继续，或换 IP；单 session 勿超过5个 |
| OPS-26 | archive.org creator: 搜索返回大量不相关结果 | creator 字段非精确匹配 | 改用 q= 全文搜索或先在浏览器获取 identifier 再用 download API |
| OPS-27 | wget Wikisource 书籍主页只得到目录页，无内容 | 内容分散在不可预测子页面 | 先 GET 主页解析章节链接，再逐章下载 |
version: '3.8'
services:
backend:
build:
context: ./backend
args:
PYTHON_BASE_IMAGE: docker.m.daocloud.io/library/python:3.11-slim
PIP_INDEX_URL: https://mirrors.aliyun.com/pypi/simple/
env_file: .env
ports:
- "${BACKEND_PORT}:8000"
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
frontend:
build:
context: ./frontend
ports:
- "${FRONTEND_PORT}:80"
restart: unless-stopped
depends_on:
- backend
关键注意点（来自踩坑）：
DEPLOY_TOKEN 不用 GITHUB_TOKEN（私有仓库可能认证失败）printf '%s\n' 不用 heredoc（<< 是 YAML 保留语法）if [ -d "$CERT_DIR" ] 才写 nginx 配置# 参考：项目群/tashan-world/.github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Deploy to server
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
script: |
cd /var/www/github-actions/repos/${{ github.event.repository.name }}
git pull origin main
# 写入 .env（用 printf 不用 heredoc）
printf '%s\n' '${{ secrets.DEPLOY_ENV }}' > .env
# 构建并启动
docker-compose down
docker-compose build --no-cache
docker-compose up
# /etc/nginx/sites-enabled/[project].tashan.chat
server {
listen 80;
server_name [project].tashan.chat;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl;
server_name [project].tashan.chat;
ssl_certificate /root/.acme.sh/[project].tashan.chat/fullchain.cer;
ssl_certificate_key /root/.acme.sh/[project].tashan.chat/[project].tashan.chat.key;
# 前端
location / {
proxy_pass http://127.0.0.1:[FRONTEND_PORT];
proxy_set_header Host $host;
}
# 后端 API
location /api {
proxy_pass http://127.0.0.1:[BACKEND_PORT];
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# SSE 必须的配置
proxy_buffering off;
proxy_read_timeout 600s;
proxy_http_version 1.1;
proxy_set_header Connection '';
}
}
□ 服务健康检查：curl https://[domain]/health → 200
□ 数据库连接：检查后端日志是否有 DB 连接错误
□ AI 调用成本：查看 DashScope 控制台每日费用
□ Docker 容器状态：docker ps → 所有容器 Up
□ 磁盘空间：df -h → 使用率 < 80%
□ 内存使用：free -h → 不超出
我接收：
我输出：
生产问题处理流程：
生产问题发现 → 开发热修复 → 测试快速回归 → DevOps 重新部署
本节由 uto-experience-hook Rule 驱动，此处为提示性说明。
执行本 Skill 过程中，若触发以下任一信号，立即追加一行到暂存区（不中断主任务）：
暂存格式（追加到 .cursor/skills/skill-index/PENDING-EXPERIENCES.md）：
| [今日日期] | [本Skill目录名] | [信号类型] | [一句话描述经验内容] | 🔲 待处理 |
所有执行步骤完成后，检查暂存区是否有新增条目。若有，在收尾时告知用户： 「本次执行感知到 N 条经验（已暂存），任务确认跑通后可说「做一次项目复盘」处理。」
根因：AGENT_RULES.md 新增 RULE-25，要求部署验证时优先使用 /api/internal/chat 接口；Skill 中虽已有 ask_server() 函数，但未明确"不需手写 SSH/Paramiko 脚本"，也未链接接口规范文档。
经验核心：部署后验证全程使用服务器 AI 接口，无需 SSH/Paramiko；接口规范集中维护于 _内部总控/开发规范/AI调用服务器助手接口规范.md。
修改内容：
## ⚠️ 部署后验证清单 原则行 → 补充"不需要手写 SSH/Paramiko 脚本"说明及接口规范文档链接验证结果：
验证状态：🔵 待验证
本 Skill 执行过程中，自动遵循 auto-experience-hook Rule 进行经验暂存。
部署调试场景下，以下情况必须触发（即使正在连续调试，也不跳过）：
「感知不打断，沉淀在任务后」——每发现一个踩坑，先用一句话暂存，继续调试，任务结束后统一处理。
根因：openclaw-proxy 项目实战中，proxy-backend 容器（172.26.0.0/16）通过 host.docker.internal 连接宿主机 WS 服务失败，踩坑速查中无此场景记录。
经验核心：容器访问宿主机服务存在三重陷阱——ufw 拦截、服务绑定 loopback、DNS 解析 IP 与实际网段不一致。TCP 连通成功不等于应用层握手成功，必须在代码层验证 WS 握手。
修改内容：
验证结果：
验证状态：🔵 待验证
适用场景：两个独立 docker compose 项目的容器需要互相访问（如 tashan-world 调用 topiclab-backend 的账号服务）。
docker-compose.yml，不合并# 项目α 的 docker-compose.yml
networks:
tashan-shared:
external: true # 声明为外部网络，不自动创建
services:
frontend:
networks:
- default
- tashan-shared
backend:
networks:
- default
- tashan-shared
# 项目β 的 docker-compose.yml（同样声明加入）
networks:
tashan-shared:
external: true
services:
backend:
container_name: topiclab-backend # 固定容器名，供跨项目引用
networks:
- default
- tashan-shared
跨项目引用的容器必须保证名称可预测，有两种方式：
| 方式 | 写法 | 适用场景 |
|---|---|---|
| 显式固定 | container_name: topiclab-backend | 推荐，名称最清晰 |
| 默认命名规则 | {项目目录名}_{服务名}_1 | 未设置 container_name 时使用 |
在调用方配置中直接用容器名作为 hostname：
# 项目α 的 nginx.conf 中跨项目调用
upstream account_service {
server topiclab-backend:8000; # 直接用容器名
}
external network 必须在 docker compose up 之前存在，否则报错。在 deploy.yml 的 script 段加入：
script: |
# 幂等创建共享网络（已存在则跳过，不报错）
docker network create tashan-shared 2>/dev/null || true
cd /var/www/github-actions/repos/${{ github.event.repository.name }}
git pull origin main
printf '%s\n' '${{ secrets.DEPLOY_ENV }}' > .env
docker compose down
docker compose build --no-cache
docker compose up -d
顺序要求：
docker network create必须在docker compose up之前执行。两个项目的 deploy.yml 都加这一行，幂等，互不干扰。
nginx 在启动时解析 upstream 中的域名/容器名。如果被引用的容器（如 topiclab-backend）在 nginx 启动后才加入 tashan-shared 网络，会导致 upstream 解析失败（502）。
处理方式：
set $backend topiclab-backend:8000; proxy_pass http://$backend;docker compose down && docker compose up -d（reload 不够，需重建容器）适用场景：需要通过公网 SSH 访问另一台机器（如 Mac ↔ Windows 跨网），无需开放公网端口。
# Step 1：从 JSON API 获取最新 pkg 名（universal-package 字段）
curl -fL "https://dl.tailscale.com/stable/?mode=json" | \
python3 -c "import sys,json; d=json.load(sys.stdin); print(d['MacZips']['universal-package'])"
# Step 2：下载 pkg（将 [pkg名] 替换为上一步输出的文件名）
curl -fL "https://dl.tailscale.com/stable/[pkg名]" -o /tmp/tailscale.pkg
# Step 3：安装（弹出系统授权对话框，免命令行 sudo）
osascript -e 'do shell script "installer -pkg /tmp/tailscale.pkg -target /" with administrator privileges'
# Step 4：启动
open -a Tailscale
连接前必须先确认双方在同一 tailnet，否则 ssh 直接超时且无任何错误提示：
# 查看 peer 列表（目标机必须出现在列表中）
/Applications/Tailscale.app/Contents/MacOS/Tailscale status
若只看到自己（no peers）：两机器登录了不同账号，不在同一 tailnet。
诊断（对比两台机器的 tailnet 域名）：
/Applications/Tailscale.app/Contents/MacOS/Tailscale whois [本机Tailscale-IP]
# 对比 Name 字段的 tailnet 域名，如 tail1610cb.ts.net vs tail226c2f.ts.net → 不同 = 不同 tailnet
解决方案：
⚠️ 管理员用户（Administrators 组成员）的公钥不放
~/.ssh/authorized_keys，必须放以下专用路径：
# 在 Windows 目标机上，以「管理员身份运行」PowerShell 执行：
$pubkey = "ssh-ed25519 AAAA... user@host"
Add-Content -Path "C:\ProgramData\ssh\administrators_authorized_keys" -Value $pubkey
# 必须设置严格权限（否则 OpenSSH 会静默忽略该文件，SSH 始终要求输入密码）
icacls "C:\ProgramData\ssh\administrators_authorized_keys" /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
根因：Windows OpenSSH 要求
administrators_authorized_keys只允许 Administrators 和 SYSTEM 访问，继承了其他权限时会静默忽略整个文件。
配置后可直接用 ssh <alias> 连接，无需每次输入 IP、用户名、密钥路径：
# ~/.ssh/config
Host <alias>
HostName <tailscale-ip>
User <username>
IdentityFile ~/.ssh/id_ed25519
StrictHostKeyChecking accept-new
同一账号重新登录 Tailscale 后 IP 可能变化（如从 100.126.144.121 变为 100.104.223.4）：
tailscale status 确认当前 IPHostName 需同步更新（否则连接超时，无明显报错）根因：tashan-openbrain 项目跨机器调试时，需要从 Mac 通过 Tailscale SSH 连接 Windows 机器，踩了以下五个坑：① 无 Homebrew 时不知如何安装 Tailscale；② tailnet 不一致导致 SSH 超时无任何报错；③ Windows 管理员用户公钥路径错误（应放 administrators_authorized_keys）；④ icacls 权限配置缺失导致公钥静默被忽略；⑤ Tailscale IP 重连后变化但 SSH config 未同步。DevOps Skill 原无任何 Tailscale/跨机器 SSH 覆盖。
经验核心：Tailscale 建立跨网 SSH 的关键前置条件是「同一 tailnet」；Windows 管理员用户需要单独处理公钥路径和权限；IP 变化是隐性陷阱。
修改内容：
## 远程访问：Tailscale 跨机器 SSH 章节（含5个知识点：macOS无Homebrew安装 / tailnet前置验证 / Windows管理员公钥配置 / SSH config别名 / IP变化注意）验证结果：
验证状态：✅ 已验证（本次任务实战验证）
适用场景：Windows 本地运行前端/后端服务，需通过
xxx.tashan.chat公网访问。
核心路径：Windows → ECS（Tailscale IP）反向 SSH 隧道 → ECS nginx → 用户浏览器
□ Windows 与 ECS 均在同一 Tailscale tailnet（`tailscale status` 确认）
□ ECS 已生成 HTTPS 证书（acme.sh，见下方「证书申请完整流程」）
□ ECS nginx 已配置对应子域名 server block
□ Windows 运行：backend（port 8001）+ frontend（vite preview，port 3104）
Windows OpenSSH 9.5p2 已知 bug：使用 ED25519 密钥时，publickey-hostbound-v00@openssh.com 扩展在无 ssh-agent 的非交互式 SSH 会话中签名静默失败（debug 日志显示 we did not send a packet, disable method），导致认证永远失败，即使密钥已在服务器 authorized_keys 中。
解决方案：生成 RSA 密钥（不触发 hostbound 扩展）：
:: 在 Windows 命令行（MSI 用户 SSH 会话中，非 WMI）
del C:\Users\MSI\.ssh\id_ed25519 C:\Users\MSI\.ssh\id_ed25519.pub
echo y | C:\WINDOWS\System32\OpenSSH\ssh-keygen.exe -t rsa -b 4096 -f C:\Users\MSI\.ssh\id_ed25519 -P ""
type C:\Users\MSI\.ssh\id_ed25519.pub
然后把公钥加入 ECS ~/.ssh/authorized_keys（通过 OpenClaw API 或 aup 中转）。
# 构建生产包
cd D:\tashan-openbrain_myagent\frontend
npm run build
# vite.config.ts 中必须加入 preview.allowedHosts: true，否则外部域名访问被阻
# preview:
# allowedHosts: true
# host: '0.0.0.0'
# port: 3104
# 启动静态文件服务（vite preview）
npm run preview -- --host 0.0.0.0 --port 3104
@echo off
:loop
C:\WINDOWS\System32\OpenSSH\ssh.exe -N ^
-o StrictHostKeyChecking=accept-new ^
-o ServerAliveInterval=30 ^
-o ServerAliveCountMax=3 ^
-R 13104:127.0.0.1:3104 ^
-R 18104:127.0.0.1:8001 ^
-i C:\Users\MSI\.ssh\id_ed25519 ^
root@<ECS Tailscale IP>
timeout /t 5 /nobreak
goto loop
注：用 ECS Tailscale IP（如
100.116.135.33），不用公网 IP（Aliyun 安全组会阻断 Windows→ECS 的直连）。
从 SSH 会话启动持久进程必须用 WMI Win32_Process.Create，用 Start-Process 在无桌面的 SSH session 中无效：
$wmi = [wmiclass]"Win32_Process"
# 后端
$wmi.Create("D:\tashan-openbrain_myagent\.venv\Scripts\python.exe -m uvicorn main:app --host 0.0.0.0 --port 8001", "D:\tashan-openbrain_myagent\backend")
# 前端（批处理文件中调用 npm.cmd）
$wmi.Create("cmd.exe /c D:\start-fe.bat", "D:\")
# 隧道
$wmi.Create("cmd.exe /c D:\start-tunnel.bat", "D:\")
server {
listen 443 ssl;
server_name sub.tashan.chat;
ssl_certificate /etc/letsencrypt/live/sub.tashan.chat/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/sub.tashan.chat/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
location /api/ {
proxy_pass http://127.0.0.1:18104/; # 反向隧道后端端口
proxy_buffering off;
proxy_read_timeout 600s;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
location / {
proxy_pass http://127.0.0.1:13104; # 反向隧道前端端口
}
}
ECS 上运行的 OpenClaw 服务提供了一个内部 API，AI 可通过此接口在 ECS 执行 shell 命令，无需 SSH 密钥直连。
import httpx
def run_on_ecs(command: str) -> str:
"""通过 OpenClaw 在 ECS（101.200.234.115）执行命令。
适用于：nginx 配置/证书申请/authorized_keys 修改等场景。
不适用于：需要停止 nginx 的命令（nginx 停止后此接口不可达）。
"""
r = httpx.post(
"https://openclaw.tashan.chat/api/internal/chat",
headers={"X-API-Key": "tashan-internal-2026"},
json={"message": command},
timeout=90,
)
return r.json()["reply"]
# 示例：查看当前 authorized_keys
# run_on_ecs("cat ~/.ssh/authorized_keys")
# 示例：添加公钥
# run_on_ecs("echo 'ssh-rsa AAAA...' >> ~/.ssh/authorized_keys")
# 示例：申请证书（webroot 模式，nginx 不停）
# run_on_ecs("mkdir -p /var/www/acme-challenge/.well-known/acme-challenge && ...")
# run_on_ecs("~/.acme.sh/acme.sh --issue --webroot /var/www/acme-challenge -d xxx.tashan.chat")
⚠️ 注意：
systemctl stop nginx 后此接口不可达（自身由 nginx 代理），需改用 aup bore 隧道 + SSH 中转ECS 加入 Tailscale 后，若 UFW 已启用，需要明确放行 Tailscale 接口和子网，否则 Tailscale 直连 SSH 仍被 UFW 阻断：
# 允许所有来自 Tailscale 接口的流量
ufw allow in on tailscale0
# 允许 Tailscale CGNAT 子网（100.64.0.0/10）的 SSH
ufw allow from 100.64.0.0/10 to any port 22 comment 'Tailscale SSH'
# 重载生效
ufw reload
验证：/Applications/Tailscale.app/Contents/MacOS/Tailscale ping <ECS Tailscale IP> 返回 pong 后，ssh root@<ECS Tailscale IP> 应可连通。
根因：第三次发生同类问题——「完成任务但没测新功能路径」。本次创建了 20 个 NPC 大脑 + Proxy 对话功能，RULE-LOC V1-V11 全部通过后宣布就绪。用户追问后才测试 Proxy 对话，发现 run_agent_stream() 缺少 system_prompt_override 参数，导致所有 NPC 的 Proxy 对话 100% 返回 500 错误。RULE-LOC 的根本缺陷：只有固定的通用检查项，没有机制要求「对本次任务新增的功能路径做端到端测试」。
问题规律（三次复现）：
修改内容：
验证结果：本次任务已验证 V11（广场20个NPC）+ V12（Proxy对话代码修复后测试，20/20）
已知风险：V11+ 的「本次任务新增了什么」需要 AI 自判断，可能遗漏低可见度变更（如 DB schema 变更对 API 的影响）。下一步可考虑在每次任务开始时明确列出「本次会影响的功能路径」。
根因：TASK-20260321-48 本地启动后未配置 DATABASE_URL 和 JWT_SECRET_KEY（.env.example 根本没有这两个变量），导致登录时返回 503「数据库未配置，Phase 2 功能不可用」。RULE-LOC 的 V7 只测了端点「存在性」（HTTP 422），未测「功能可用性」（HTTP 401 vs 503），是验证覆盖不足。
修改内容：
配套修改：
验证结果：✅ 本次任务 V10 通过（数据库已连通，登录返回 401）
根因：TASK-20260321-48（tashan-openbrain 本地启动）完成后，只做了一条 curl /health 就说「✅ 任务完成」。原因是 DevOps Skill 只有生产 Docker 验证清单，没有本地 dev 启动的验证步骤，缺少明确约束。用户指出这是规范缺失。
修改内容：
验证结果：
已知风险：V6「本次新增路由」需要 AI 自己判断哪些是「本次新增」，有遗漏风险——可通过任务日志回顾确认
验证状态：✅ 本次任务已验证
根因：① PD-001 沙盘验证发现部署完成后缺乏触发 project-closeout 的机制，收尾链路断裂；② 先前缺少「接口通了但界面卡死」的浏览器层验证。
修改内容：
验证结果：
验证状态：🔵 待验证
根因：myagent 项目 Windows 本地进程公网化部署全链路实战中，踩了五个高频坑：① Aliyun 安全组阻断 Windows→ECS 直连，必须走 Tailscale；② Windows OpenSSH 9.5p2 ED25519 publickey-hostbound 静默失败，只能用 RSA；③ Start-Process 在无桌面 SSH 会话中无法持久化进程，必须用 WMI；④ vite preview 默认拒绝外部 Host，须设 allowedHosts: true；⑤ ECS Tailscale 接入后 UFW 未放行 tailscale0，Tailscale 直连 SSH 被阻断。此外，通过 OpenClaw API 在 ECS 执行命令（无需 SSH 密钥）是部署中的核心便捷工具，但之前无 Skill 覆盖。
经验核心：Windows 公网化的三个关键约束：① Tailscale 绕过安全组；② RSA 密钥绕过 OpenSSH bug；③ WMI 绕过 SSH session 生命周期限制。
修改内容：
## Windows 本地进程公网化（反向 SSH 隧道模式） 章节（含 RSA 密钥/vite preview/WMI/nginx 模板）## OpenClaw API：在 ECS 上执行命令 章节（含 Python 调用模板和使用限制）## ECS 接入 Tailscale 后的 UFW 配置 章节（含 tailscale0/100.64.0.0/10 规则）验证结果：
https://openbrain-win.tashan.chat 已通过本次链路实测，HTTP 200 ✅验证状态：✅ 已验证（2026-03-22 myagent Windows 公网化实战）
根因：tashan-world 调用 topiclab-backend 账号服务时，发现跨 docker compose 项目的容器通信没有对应的 Skill 覆盖，只能凭经验摸索。实战验证后发现 external network 是标准做法，且有多个细节易错（network 须先建、container_name 须固定、nginx DNS 解析时机）。
经验核心：跨项目容器通信的正确架构是 docker external network；deploy.yml 必须幂等创建该 network；nginx upstream 的容器名解析在启动时发生，容器必须先入网。
修改内容：
## 跨项目容器网络架构（tashan-shared 模式） 章节（含 external network 配置模板、container_name 稳定性说明、deploy.yml 幂等创建命令、nginx DNS 解析注意事项）验证结果：
验证状态：🔵 待验证
根因：role-DevOps 导航表缺少 D0 认知根确认行，AI 执行时没有「先确认当前生产环境状态」的强制步骤（连接缺口）。
修改内容：
验证状态：🔵 待验证
备份路径：history/SKILL_v1.3.0_20260323_before_nav.md