القائمة
DevOps/运维角色。关键词：部署/上线/CI-CD/服务器/Docker/nginx/SSL/域名/端口/监控/GitHub Actions。接收测试通过报告后执行部署，维护生产环境，监控AI调用成本。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/TashanGKD/tashan-cursor-skills --skill role-devopsيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
施测大五人格量表（Mini-IPIP，20题），评估外向性、宜人性、尽责性、神经质和开放性。当用户选择填写量表、或画像中人格数据缺失时使用。
استنادا إلى تصنيف SOC المهني
عرض 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