feat: 新增 deploy Skill 与 LA 生产部署文档

线上为 1 核 1.9G 机器，放弃 Docker：Node 直跑 + systemd 守护，前端本地构建后由服务端静态托管，HTTPS 与反代由 aaPanel 的 nginx 管理。部署脚本支持 web／server／all 三种目标，含本地类型检查与单测、暂存目录原子换入、健康检查失败自动回滚源码、本地与远端源码树指纹比对及公网校验。首次部署与一次性配置写在 docs/DEPLOY.md。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-09-03 17:38:38 +08:00
parent 6ea1f28940
commit 43a753963c
4 changed files with 261 additions and 0 deletions
--- a/.claude/skills/deploy/SKILL.md
+++ b/.claude/skills/deploy/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: deploy
+description: 把 proxy-station 部署到 LA 生产服务器（ps.la.njcqtechaicoding.com）。可以只部署前端、只部署后端，或前后端一起。凡是用户提到「部署」「发布」「上线」「推到服务器」「更新线上」「让线上生效」「同步到 la」，或改完代码想在生产环境看效果，都用这个 Skill，即使没有明说「部署」二字。
+---
+
+# 部署 proxy-station 到 LA
+
+线上是一台 1 核 1.9G 的机器，没有 Docker：后端用 Node 22 直跑、systemd 守护（服务名 `proxy-station`，代码在 `/opt/proxy-station`），前端在本机构建后由后端静态托管，HTTPS 与反代由 aaPanel 的 nginx 负责。首次部署与一次性配置（systemd 单元、`/etc/proxy-station/env`、nginx 站点、证书、数据库迁移）见 `docs/DEPLOY.md`，本 Skill 只负责日常的代码更新。
+
+## 用法
+
+```bash
+bash .claude/skills/deploy/scripts/deploy.sh all       # 前后端一起（默认）
+bash .claude/skills/deploy/scripts/deploy.sh web       # 只换前端产物，不重启服务
+bash .claude/skills/deploy/scripts/deploy.sh server    # 只推后端源码，装依赖并重启服务
+```
+
+可选开关：
+
+| 开关 | 作用 | 什么时候用 |
+|---|---|---|
+| `--skip-checks` | 跳过本地 typecheck 与单测 | 本轮已经跑过且代码没再改 |
+| `--skip-build` | 不重新构建前端，直接推现有 `web/dist` | 刚构建过，只是重推 |
+| `--host <别名>` | 换目标机器（默认 `la`） | 以后有第二台时 |
+
+也可用环境变量覆盖 `DEPLOY_REMOTE_DIR`、`DEPLOY_SERVICE`、`DEPLOY_PUBLIC_URL`、`DEPLOY_RUN_USER`。
+
+## 怎么选目标
+
+- 改动只在 `web/` 下（页面、样式、前端逻辑）→ `web`。前端产物是静态文件，后端按请求读盘，换完立刻生效，不打断已连接的客户端拉订阅。
+- 改动在 `server/` 或 `shared/` → `server`。`shared/` 是前后端共用源码，动了它通常前端也要重建，这时用 `all` 更稳。
+- 拿不准就用 `all`，多花的只是一次前端构建的几秒钟。
+
+## 脚本做了什么，以及为什么
+
+1. **预检**：拒绝大写 ssh 别名（大写会被当作域名走 fake-IP 解析，连不上）；确认远端目录与 systemd 单元存在，否则提示先做首次部署。
+2. **本地检查**：后端目标先跑 typecheck 与单测。线上没有测试环境，这是最后一道拦截。
+3. **推送**：用 tar 管道走 ssh，不依赖远端 rsync。先解到暂存目录再整体换入，旧版本保留为 `*.old`，中途失败不会留下半新半旧的目录。
+4. **后端**：`pnpm install --frozen-lockfile --prod` 只装 server 及其 workspace 依赖，然后重启服务，等 `/api/health` 最多 20 秒。不通过就打印日志、把源码换回 `.old` 并重启，让线上先恢复。
+5. **校验**：不用「命令没报错」当成功。前端比对本地与远端 `web/dist` 的文件树指纹，并检查公网首页是否已引用新的入口脚本；后端比对 `server/src` 与 `shared/src` 的指纹并确认服务 active；最后从本机访问公网健康检查，并确认管理接口不带 token 时返回 401。任何一项不过，脚本以失败退出。
+
+脚本运行时会主动剥掉会话注入的 HTTP 代理环境变量，ssh／pnpm／curl 都直连。
+
+## 结果怎么读
+
+- 最后一行 `部署完成：<目标> @ <git rev>` 才算成功。把这一行连同校验段落转述给用户。
+- 输出里出现 `（工作区有未提交改动）` 时要提醒用户：线上跑的是未提交的代码，之后应当提交或有意识地保持。
+- `前端产物指纹不一致` 几乎只有一种原因：推送中断。重跑一次 `web` 即可。
+- `公网首页未引用 <入口脚本>` 而指纹一致：浏览器或中间缓存，稍等再试；aaPanel 的反代模板对 js 只缓存 1 分钟。
+- `pnpm install 失败`：多半是本地 `package.json` 改了但锁文件没更新。本地 `pnpm install` 后连锁文件一起提交，再部署。
+- 健康检查失败并回滚：回滚只恢复源码，不恢复依赖。到本地用 `pnpm --filter @proxy-station/server start` 复现，别在线上反复重启。
+
+## 边界
+
+- 不迁移数据库、不改 `ADMIN_TOKEN`、不碰 nginx 与证书。这些操作见 `docs/DEPLOY.md`，且每一项都应先跟用户确认。
+- 不做 git 提交。部署与提交是两件事，用户没要求就不要顺手提交。
+- 如果用户要部署到 LA 之外的机器，先确认那台机器已按 `docs/DEPLOY.md` 完成首次部署，再用 `--host` 与环境变量指向它。
--- a/.claude/skills/deploy/scripts/deploy.sh
+++ b/.claude/skills/deploy/scripts/deploy.sh
@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# proxy-station 部署脚本：把前端产物／后端源码推到 LA 服务器（Node 直跑 + systemd，nginx 由 aaPanel 管）
+#
+#   deploy.sh [web|server|all] [--skip-checks] [--skip-build] [--host <ssh别名>]
+#
+#   web     只构建并替换前端静态产物（服务端按请求读盘，不需要重启）
+#   server  只推送 shared/ 与 server/ 源码，安装生产依赖并重启 systemd 服务
+#   all     两者都做（默认）
+#
+# 数据库、/etc/proxy-station/env、nginx 站点与证书一律不碰——那些是一次性配置，见 docs/DEPLOY.md。
+set -euo pipefail
+
+# 会话注入的 HTTP 代理只供模型 API 使用，ssh／pnpm／curl 一律直连
+unset HTTPS_PROXY https_proxy HTTP_PROXY http_proxy ALL_PROXY NO_PROXY no_proxy
+
+HOST="${DEPLOY_HOST:-la}"
+REMOTE_DIR="${DEPLOY_REMOTE_DIR:-/opt/proxy-station}"
+SERVICE="${DEPLOY_SERVICE:-proxy-station}"
+RUN_USER="${DEPLOY_RUN_USER:-proxy-station}"
+PUBLIC_URL="${DEPLOY_PUBLIC_URL:-https://ps.la.njcqtechaicoding.com}"
+LOCAL_PORT="${DEPLOY_LOCAL_PORT:-3000}"
+
+TARGET=all
+SKIP_CHECKS=0
+SKIP_BUILD=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    web|server|all) TARGET="$1" ;;
+    --skip-checks) SKIP_CHECKS=1 ;;
+    --skip-build) SKIP_BUILD=1 ;;
+    --host) shift; HOST="$1" ;;
+    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
+    *) echo "未知参数：$1（可用：web|server|all --skip-checks --skip-build --host <别名>）" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || { cd "$(dirname "$0")/../../../.." && pwd; })"
+cd "$ROOT"
+
+SSH=(ssh -o BatchMode=yes -o ConnectTimeout=15 "$HOST")
+step() { printf '\n\033[1;34m==> %s\033[0m\n' "$*"; }
+fail() { printf '\033[1;31m!! %s\033[0m\n' "$*" >&2; exit 1; }
+
+# 本地与远端各算一遍「源码树指纹」：文件按路径排序后逐个取 sha256，再对哈希列表取 sha256。
+# 部署完两边一致就能确定推上去的就是本地这份，而不是靠「命令没报错」来猜。
+hash_cmd_local() { command -v sha256sum >/dev/null && echo sha256sum || echo 'shasum -a 256'; }
+tree_hash_local() {
+  local h; h="$(hash_cmd_local)"
+  find "$@" -type f ! -name '*.test.ts' | LC_ALL=C sort | xargs $h | awk '{print $1}' | $h | awk '{print $1}'
+}
+tree_hash_remote() {
+  "${SSH[@]}" "cd '$REMOTE_DIR' && find $* -type f ! -name '*.test.ts' | LC_ALL=C sort | xargs sha256sum | awk '{print \$1}' | sha256sum | awk '{print \$1}'"
+}
+
+# ---------- 预检 ----------
+step "预检：ssh 别名 ${HOST}、远端目录、服务状态"
+case "$HOST" in *[[:upper:]]*) fail "ssh 别名请用小写（大写会被当成域名走 fake-IP 解析而连不上）";; esac
+"${SSH[@]}" "test -d '$REMOTE_DIR/server' && test -f /etc/systemd/system/$SERVICE.service" \
+  || fail "远端缺少 $REMOTE_DIR/server 或 systemd 单元，请先按 docs/DEPLOY.md 完成首次部署"
+GIT_REV="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+GIT_DIRTY="$(git status --porcelain 2>/dev/null | grep -q . && echo '（工作区有未提交改动）' || true)"
+echo "本地版本：$GIT_REV $GIT_DIRTY"
+echo "目标：$TARGET → $HOST:$REMOTE_DIR"
+
+# ---------- 本地检查与构建 ----------
+if [ "$TARGET" != web ] && [ "$SKIP_CHECKS" = 0 ]; then
+  step "本地类型检查与单测（--skip-checks 可跳过）"
+  pnpm -r typecheck >/dev/null || fail "typecheck 失败，先修再部署"
+  pnpm test 2>&1 | tail -4
+fi
+if [ "$TARGET" != server ]; then
+  if [ "$SKIP_BUILD" = 0 ]; then
+    step "构建前端"
+    pnpm --filter @proxy-station/web build 2>&1 | tail -3
+  else
+    step "跳过构建，使用现有 web/dist"
+  fi
+  test -f web/dist/index.html || fail "web/dist/index.html 不存在"
+fi
+
+# ---------- 推送 ----------
+# macOS 的 bsdtar 会把文件 xattr 写成扩展头，远端 GNU tar 每个文件刷一行「unknown extended header」；两端各关一次
+TAR_EXCLUDES=(--no-xattrs --exclude='node_modules' --exclude='*.test.ts' --exclude='.DS_Store' --exclude='data' --exclude='*.db*' --exclude='.env')
+export COPYFILE_DISABLE=1
+UNTAR='tar xzf - --warning=no-unknown-keyword'
+
+if [ "$TARGET" != server ]; then
+  step "推送前端产物 → $REMOTE_DIR/web/dist（原子替换，旧版保留为 dist.old）"
+  tar czf - "${TAR_EXCLUDES[@]}" web/dist | "${SSH[@]}" "set -e; cd '$REMOTE_DIR'; rm -rf .staging-web; mkdir .staging-web; $UNTAR -C .staging-web;
+    rm -rf web/dist.old; [ -d web/dist ] && mv web/dist web/dist.old; mv .staging-web/web/dist web/dist; rm -rf .staging-web;
+    chown -R $RUN_USER:$RUN_USER web/dist"
+fi
+
+if [ "$TARGET" != web ]; then
+  step "推送后端源码与锁文件 → ${REMOTE_DIR}（旧源码保留为 src.old 以便回滚）"
+  tar czf - "${TAR_EXCLUDES[@]}" package.json pnpm-workspace.yaml pnpm-lock.yaml \
+    shared/package.json shared/tsconfig.json shared/src \
+    server/package.json server/tsconfig.json server/src \
+    web/package.json \
+  | "${SSH[@]}" "set -e; cd '$REMOTE_DIR'; rm -rf .staging; mkdir .staging; $UNTAR -C .staging;
+    for d in server/src shared/src; do rm -rf \"\$d.old\"; [ -d \"\$d\" ] && mv \"\$d\" \"\$d.old\"; mv \".staging/\$d\" \"\$d\"; done;
+    cp .staging/package.json .staging/pnpm-workspace.yaml .staging/pnpm-lock.yaml .;
+    cp .staging/shared/package.json .staging/shared/tsconfig.json shared/;
+    cp .staging/server/package.json .staging/server/tsconfig.json server/;
+    cp .staging/web/package.json web/; rm -rf .staging"
+
+  step "远端安装生产依赖（frozen lockfile）"
+  "${SSH[@]}" "cd '$REMOTE_DIR' && CI=true pnpm install --frozen-lockfile --prod --filter '@proxy-station/server...' 2>&1 | tail -3 && chown -R $RUN_USER:$RUN_USER '$REMOTE_DIR'" \
+    || fail "pnpm install 失败。锁文件与 package.json 不一致时先在本地 pnpm install 并提交锁文件"
+
+  step "重启 $SERVICE 并等待健康检查"
+  "${SSH[@]}" "systemctl restart $SERVICE"
+  if ! "${SSH[@]}" "for i in \$(seq 1 20); do curl -sf -m 2 http://127.0.0.1:$LOCAL_PORT/api/health >/dev/null && exit 0; sleep 1; done; exit 1"; then
+    echo "健康检查 20 秒未通过，最近日志："
+    "${SSH[@]}" "journalctl -u $SERVICE -n 30 --no-pager -o cat" || true
+    step "回滚到上一版源码"
+    "${SSH[@]}" "set -e; cd '$REMOTE_DIR'; for d in server/src shared/src; do [ -d \"\$d.old\" ] && rm -rf \"\$d\" && mv \"\$d.old\" \"\$d\"; done; chown -R $RUN_USER:$RUN_USER .; systemctl restart $SERVICE"
+    fail "已回滚到旧源码并重启（锁文件与依赖未回滚）。请在本地复现后再部署"
+  fi
+fi
+
+# ---------- 校验 ----------
+step "校验"
+"${SSH[@]}" "printf 'rev=%s target=%s at=%s\n' '$GIT_REV' '$TARGET' \"\$(date -Is)\" > '$REMOTE_DIR/.deploy-stamp'"
+OK=1
+if [ "$TARGET" != server ]; then
+  L="$(tree_hash_local web/dist)"; R="$(tree_hash_remote web/dist)"
+  [ "$L" = "$R" ] && echo "前端产物指纹一致：${L:0:12}" || { echo "前端产物指纹不一致：本地 ${L:0:12} 远端 ${R:0:12}"; OK=0; }
+  ASSET="$(grep -oE 'assets/index-[A-Za-z0-9_-]+\.js' web/dist/index.html | head -1)"
+  if curl -sf -m 10 "$PUBLIC_URL/" | grep -q "$ASSET"; then echo "公网首页已引用新入口脚本 $ASSET"; else echo "公网首页未引用 ${ASSET}（缓存或部署失败）"; OK=0; fi
+fi
+if [ "$TARGET" != web ]; then
+  L="$(tree_hash_local server/src shared/src)"; R="$(tree_hash_remote server/src shared/src)"
+  [ "$L" = "$R" ] && echo "后端源码指纹一致：${L:0:12}" || { echo "后端源码指纹不一致：本地 ${L:0:12} 远端 ${R:0:12}"; OK=0; }
+  "${SSH[@]}" "systemctl is-active --quiet $SERVICE" && echo "systemd 服务 active" || { echo "systemd 服务未运行"; OK=0; }
+fi
+if curl -sf -m 10 "$PUBLIC_URL/api/health" | grep -q '"ok":true'; then echo "公网健康检查通过：$PUBLIC_URL/api/health"; else echo "公网健康检查失败"; OK=0; fi
+CODE="$(curl -s -o /dev/null -m 10 -w '%{http_code}' "$PUBLIC_URL/api/nodes")"
+[ "$CODE" = 401 ] && echo "管理接口未带 token 返回 401，鉴权正常" || { echo "管理接口未带 token 返回 ${CODE}，预期 401"; OK=0; }
+
+[ "$OK" = 1 ] && step "部署完成：$TARGET @ $GIT_REV → $PUBLIC_URL" || fail "部署校验有未通过项，见上"
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,6 +19,9 @@ npx vitest run parse                 # 按文件名
 npx vitest run -t "round-trip"       # 按用例名
 npx vitest                           # watch 模式

+# 部署到 LA 生产机（web|server|all），详见 .claude/skills/deploy/SKILL.md 与 docs/DEPLOY.md
+bash .claude/skills/deploy/scripts/deploy.sh all
+
 # 校验生成的 Clash 配置（最有价值的一条端到端验证）
 curl -s "http://localhost:3000/sub/<token>/clash" > /tmp/c.yaml && mihomo -t -f /tmp/c.yaml
 ```
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -0,0 +1,59 @@
+# 生产部署（LA 节点，无 Docker）
+
+服务器资源有限（1 核／1.9G），采用 Node 直跑 + systemd 守护，前端在本机构建后由服务端静态托管，反向代理与证书由 aaPanel 管理。
+
+## 拓扑
+
+```
+客户端 ──HTTPS──▶ nginx（aaPanel 站点 ps.la.njcqtechaicoding.com，泛域名证书）
+                     └─ proxy_pass http://127.0.0.1:3000 ──▶ proxy-station（systemd，用户 proxy-station）
+```
+
+| 项目 | 位置 |
+|---|---|
+| 代码 | `/opt/proxy-station`（含 `web/dist` 构建产物，无 `web/src`） |
+| 数据库 | `/opt/proxy-station/data/proxy-station.db` |
+| 环境变量 | `/etc/proxy-station/env`（`PORT`／`DATA_DIR`／`ADMIN_TOKEN`，权限 600） |
+| 服务 | `systemctl status proxy-station`，日志 `journalctl -u proxy-station -f` |
+| nginx 站点 | aaPanel 站点 `ps.la.njcqtechaicoding.com`，反代配置在 `/www/server/panel/vhost/nginx/proxy/<域名>/` |
+| 证书 | `/www/server/panel/vhost/cert/<域名>/`，由 acme.sh 续期钩子统一复制 |
+
+`ADMIN_TOKEN` 在 Web 界面「设置」页填入，存于浏览器 localStorage。
+
+## 更新代码
+
+日常更新用项目级 Skill `deploy`（对 Claude 说「部署」即可触发），也可直接跑脚本：
+
+```bash
+bash .claude/skills/deploy/scripts/deploy.sh all      # 前后端一起（默认）
+bash .claude/skills/deploy/scripts/deploy.sh web      # 只换前端产物，不重启
+bash .claude/skills/deploy/scripts/deploy.sh server   # 只推后端源码，装依赖并重启
+```
+
+脚本自带本地 typecheck／单测、tar 管道推送、暂存目录原子换入、健康检查失败自动回滚源码，以及本地与远端的源码树指纹比对与公网校验。细节见 `.claude/skills/deploy/SKILL.md`。
+
+SSH 别名必须用小写 `la`，大写会被当作域名解析。
+
+## 迁移数据库
+
+用 sqlite3 在线备份导出一致副本，避免直接拷贝带 WAL 的库文件：
+
+```bash
+sqlite3 server/data/proxy-station.db ".backup /tmp/ps.db"
+scp /tmp/ps.db la:/tmp/ps.db
+ssh la 'systemctl stop proxy-station && install -m 644 -o proxy-station -g proxy-station /tmp/ps.db /opt/proxy-station/data/proxy-station.db && rm -f /opt/proxy-station/data/proxy-station.db-wal /opt/proxy-station/data/proxy-station.db-shm /tmp/ps.db && systemctl start proxy-station'
+```
+
+## 反向代理注意点
+
+- aaPanel 的反代模板不带 `X-Forwarded-Proto`／`X-Forwarded-Host`，已手工补进反代配置。服务端 `routes/sub.ts` 的 `baseUrl()` 依赖这两个头还原外部地址，缺失时 Surge 的 `#!MANAGED-CONFIG` 与 Clash 的 provider URL 会变成 `http://`。
+- 站点通过面板类 `AddSite`／`SetSSL`／`CreateProxy`／`HttpToHttps` 创建（脚本模式见 edge-nodes 的 `09-aapanel-sites.py`），不要手写 vhost，否则面板里看不到。
+- 泛域名 `*.la.njcqtechaicoding.com` 的 DNS 已指向服务器，新子域无需单独加记录。
+- acme.sh 的 `--reloadcmd` 要把新站点加进复制循环，且证书源路径必须写死（原先引用未定义的 `$SRC`，续期后不会重新部署证书）。
+
+## 验证
+
+```bash
+curl -s https://ps.la.njcqtechaicoding.com/api/health
+curl -s "https://ps.la.njcqtechaicoding.com/sub/<token>/clash" > /tmp/c.yaml && mihomo -t -f /tmp/c.yaml
+```