docs: add development-machine handoff and server deploy configs

换开发机继续开发。新机器只需要拉仓库 + 自备工具链 + 单独拷贝两个机密文件，服务器/聚石塔/SAE 全部沿用，不需要重建。 - docs/HANDOFF-2026-11-02.md：开发机交接（环境、仓库地图、三套测试、本地怎么跑、云端资源清单、上线方式、11 条关键结论、9 项待办、故障对照表） - deploy/：服务器侧配置入库（原先只存在于机器上） - systemd/juzi-taobao.service（18081，独立数据目录与凭据文件） - nginx/tb-location.conf（/tb/ 反代 + 只放行聚石塔 NAT EIP） - add-tb-nginx.sh（幂等插入，先备份，nginx -t 通过才 reload） - README.md（重建与回滚步骤） - tools/env-java.ps1：优先用仓库内便携工具链，缺失时回退 JAVA_HOME/PATH，换机器不用再下便携 JDK/Maven - README.md：交接文档入口更新
2026-11-01 23:34:26 +08:00
parent fed52930cc
commit 43a5373233
7 changed files with 564 additions and 15 deletions
@@ -0,0 +1,127 @@
+# deploy —— 1me.xajuzi.com 上的「淘宝专用」Node 实例
+
+这份目录存放**不在 git 里自动生效**的服务器侧配置：systemd unit、nginx 片段、安装脚本。
+换机器/换人接手时，按本文重建即可。
+
+## 拓扑
+
+```
+淘宝小程序（taobao/，AppKey 35486228）
+  → 淘宝云网关（注入 app_key / open_id / sign，单请求 10s / 128KB 上限）
+  → 聚石塔云应用 1me-net(62829) → 私网 CLB 192.168.65.185:80
+  → SAE 应用 nnn（taobao-mvp-backend-0.0.4-forward.jar，mode=forward，纯透传）
+  → 聚石塔 NAT 网关出网（EIP 47.92.113.176）
+  → https://1me.xajuzi.com/tb/  （nginx 白名单只放行上面这个 EIP）
+  → juzi-taobao.service（Node，127.0.0.1:18081，本文档这套配置）
+  → 旷视 Face++ skinanalyze_pro
+```
+
+生产 H5（`/state/`）和红书渠道（`/rednote/`）跑在同机另外两个 systemd 服务上，**8080/8081 端口，和本实例完全隔离**。
+
+## 三个服务的分工
+
+| 服务 | 端口 | 代码目录 | 用途 |
+|---|---|---|---|
+| `juzi-h5.service` | 8080 | `/home/ubuntu/juzi/h5` | 生产 H5（微信登录、报告、后台） |
+| `juzi-rednote.service` | 8081 | `/home/ubuntu/juzi-rednote/current/h5` | 小红书渠道隔离实例 |
+| `juzi-taobao.service` | 18081 | `/home/ubuntu/juzi-tb/h5` | **本目录新增**：淘宝小程序专用 |
+
+## 重建步骤
+
+### 1. 代码
+
+`/home/ubuntu/juzi-tb` 是**独立的一份 h5 代码**（不是生产目录的软链），来自本仓库的 `h5/`。
+部署方式（本地执行，把仓库里的 h5 打包传上去）：
+
+```powershell
+# 本地仓库根目录
+tar -czf temp/juzi-h5.tgz --exclude=h5/data --exclude=h5/test --exclude=h5/scripts -C . h5
+scp temp/juzi-h5.tgz ubuntu@1me.xajuzi.com:/tmp/
+```
+
+```bash
+# 服务器上
+sudo mkdir -p /home/ubuntu/juzi-tb /home/ubuntu/juzi-tb-data
+sudo chown -R ubuntu:ubuntu /home/ubuntu/juzi-tb /home/ubuntu/juzi-tb-data
+chmod 700 /home/ubuntu/juzi-tb-data
+tar -xzf /tmp/juzi-h5.tgz -C /home/ubuntu/juzi-tb
+
+# 旷视凭据复用生产那份（gitignored，不随仓库走）
+mkdir -p /home/ubuntu/juzi-tb/reference/facepp-skinanalyze
+cp /home/ubuntu/juzi/reference/facepp-skinanalyze/credentials.env \
+   /home/ubuntu/juzi-tb/reference/facepp-skinanalyze/credentials.env
+chmod 600 /home/ubuntu/juzi-tb/reference/facepp-skinanalyze/credentials.env
+```
+
+> `h5/server.js` 启动时如果找不到旷视 key 会直接 `exit(1)`，所以这一步不能漏。
+
+### 2. 淘宝凭据
+
+```bash
+sudo mkdir -p /etc/juzi
+sudo tee /etc/juzi/taobao.env >/dev/null <<'EOF'
+TAOBAO_APP_KEY=35486228
+TAOBAO_APP_SECRET=<35486228 的 AppSecret，向项目负责人索取>
+EOF
+sudo chmod 600 /etc/juzi/taobao.env && sudo chown root:root /etc/juzi/taobao.env
+```
+
+这个文件被 `h5/lib/taobao-auth.js` 读取，用于校验云网关签名。**没有它，`/session` 一律 401。**
+
+### 3. systemd
+
+```bash
+scp deploy/systemd/juzi-taobao.service ubuntu@1me.xajuzi.com:/tmp/
+ssh ubuntu@1me.xajuzi.com "sudo install -m 644 -o root -g root /tmp/juzi-taobao.service /etc/systemd/system/ \
+  && sudo systemctl daemon-reload && sudo systemctl enable --now juzi-taobao && systemctl is-active juzi-taobao"
+```
+
+### 4. nginx
+
+```bash
+# 本地
+scp deploy/add-tb-nginx.sh deploy/nginx/tb-location.conf ubuntu@1me.xajuzi.com:/tmp/
+
+# 服务器
+ssh ubuntu@1me.xajuzi.com "sed -i 's/\r\$//' /tmp/add-tb-nginx.sh && bash /tmp/add-tb-nginx.sh /tmp/tb-location.conf"
+```
+
+脚本是幂等的（检测到 `location /tb/` 就跳过），会先备份成 `juzi.bak-tb-<时间戳>`。
+
+### 5. 验收
+
+```bash
+# 服务器本机（127.0.0.1 在白名单里）
+curl -sk -H 'Host: 1me.xajuzi.com' https://127.0.0.1/tb/api/health
+# 期望 {"ok":true}
+
+# 公网（应被白名单挡掉）
+curl -s -o /dev/null -w '%{http_code}\n' https://1me.xajuzi.com/tb/api/health
+# 期望 403
+
+# 生产 H5 不受影响
+curl -s -o /dev/null -w '%{http_code}\n' https://1me.xajuzi.com/state/api/health
+# 期望 200
+```
+
+最后在聚石塔 SAE 容器里再验一次（这是唯一走 NAT 的路径）：
+
+```bash
+curl -s https://1me.xajuzi.com/tb/api/health   # 期望 {"ok":true}
+```
+
+## 回滚
+
+```bash
+sudo systemctl disable --now juzi-taobao
+sudo cp /etc/nginx/sites-available/juzi.bak-tb-<时间戳> /etc/nginx/sites-available/juzi
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+生产两个服务完全不受影响（端口、目录、数据都是独立的）。
+
+## 数据
+
+- 运行数据：`/home/ubuntu/juzi-tb-data`（700）—— 照片 `photos/`、原始返回 `results/`、记录 `records.jsonl`、账号 `accounts/`
+- 与生产的 `/home/ubuntu/juzi/h5/data` 完全分开，两边用户/报告不互通
+- **没有任何自动清理**：每次检测约 10–12MB 常驻磁盘，长期要换 OSS + RDS
@@ -0,0 +1,47 @@
+#!/bin/bash
+# 幂等地把 deploy/nginx/tb-location.conf 插入 /etc/nginx/sites-available/juzi。
+# 只做「插入一段 location」，不改动任何已有 location；先备份，nginx -t 通过才 reload。
+#
+# 用法（在 1me.xajuzi.com 上）：
+#   scp deploy/add-tb-nginx.sh deploy/nginx/tb-location.conf ubuntu@1me.xajuzi.com:/tmp/
+#   ssh ubuntu@1me.xajuzi.com "sed -i 's/\r$//' /tmp/add-tb-nginx.sh && bash /tmp/add-tb-nginx.sh"
+set -euo pipefail
+
+CONF=/etc/nginx/sites-available/juzi
+SNIPPET=${1:-/tmp/tb-location.conf}
+STAMP=$(date +%Y%m%d%H%M%S)
+BACKUP="$CONF.bak-tb-$STAMP"
+
+if grep -q 'location /tb/' "$CONF"; then
+    echo "SKIP: /tb/ 已存在，不重复插入"
+    exit 0
+fi
+if [ ! -f "$SNIPPET" ]; then
+    echo "缺少片段文件: $SNIPPET" >&2
+    exit 1
+fi
+
+sudo cp "$CONF" "$BACKUP"
+echo "BACKUP: $BACKUP"
+
+sudo python3 - "$CONF" "$SNIPPET" <<'PY'
+import sys
+
+conf_path, snippet_path = sys.argv[1], sys.argv[2]
+text = open(conf_path, encoding='utf-8').read()
+snippet = open(snippet_path, encoding='utf-8').read()
+
+block = "# BEGIN taobao-debug 2026-11-01\n" + snippet + "# END taobao-debug 2026-11-01\n\n"
+marker = "    location / {\n"
+if marker not in text:
+    sys.exit("marker 'location / {' not found")
+text = text.replace(marker, block + marker, 1)
+open(conf_path, 'w', encoding='utf-8').write(text)
+print("INSERTED")
+PY
+
+echo "--- nginx -t ---"
+sudo nginx -t
+echo "--- reload ---"
+sudo systemctl reload nginx
+echo "RELOADED"
@@ -0,0 +1,25 @@
+# 插入到 /etc/nginx/sites-available/juzi 的 HTTPS server { } 块内。
+# 作用：给淘宝小程序云网关一个专用入口 /tb/，反代到 juzi-taobao.service(127.0.0.1:18081)。
+#
+# 为什么要 allow 白名单：/tb/ 暴露在公网，后面是真实旷视计费调用。
+# 只允许聚石塔 NAT 的出口 EIP（以及本机自测）访问，其余一律 403。
+#
+# 注意：nginx 会剥掉 /tb/ 前缀，所以 /tb/api/taobao/session → Node 收到 /api/taobao/session，
+# 与 h5/server.js 的路由完全一致。
+location = /tb {
+    return 301 /tb/;
+}
+location /tb/ {
+    # 聚石塔 NAT 网关绑定的 EIP。换环境时改这一行。
+    allow 47.92.113.176;
+    # 本机自测（curl -H 'Host: 1me.xajuzi.com' https://127.0.0.1/tb/api/health）
+    allow 127.0.0.1;
+    deny all;
+
+    proxy_pass http://127.0.0.1:18081/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 150s;
+}
@@ -0,0 +1,29 @@
+[Unit]
+Description=1me taobao mini program backend (Node, /tb/ debug instance)
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/home/ubuntu/juzi-tb/h5
+# 独立于生产 juzi-h5(8080)/juzi-rednote(8081)：独立端口、独立数据目录、独立凭据文件
+Environment=JUZI_ENTRY_MODE=state
+Environment=NODE_ENV=production
+Environment=HOST=127.0.0.1
+Environment=PORT=18081
+Environment=JUZI_DATA_ROOT=/home/ubuntu/juzi-tb-data
+Environment=TRUST_LOOPBACK_PROXY=1
+# 内容格式：
+#   TAOBAO_APP_KEY=35486228
+#   TAOBAO_APP_SECRET=<35486228 的 AppSecret>
+# 权限 600 root，绝不入库。
+EnvironmentFile=/etc/juzi/taobao.env
+ExecStart=/usr/bin/node /home/ubuntu/juzi-tb/h5/server.js
+Restart=on-failure
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target