部署运行手册（备案下来后照此执行）

当前阻塞：①国内服务器 ICP 备案（7–20 天）②小程序真实 AppID/AppSecret。 备案 + 拿到 AppID 后，按下面顺序，全程约 20 分钟。

0. 前置

• 一台已备案域名指向的国内服务器（Ubuntu）
• 子域名（如 labapi.你的备案域名）DNS A 记录指向该服务器
• 已装：Node ≥ 18、PostgreSQL、Caddy、（可选）PM2

# 装 Node 20 / PostgreSQL / Caddy（Ubuntu 示例）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
sudo apt install -y postgresql caddy
sudo npm i -g pm2

1. 拉代码

sudo mkdir -p /opt/labcalc-server && sudo chown $USER /opt/labcalc-server
git clone <仓库地址> /opt/labcalc-server
cd /opt/labcalc-server

2. 数据库

# 改掉 setup-db.sql 里的密码后执行
sudo -u postgres psql -f deploy/setup-db.sql

3. 配置 .env

cp .env.example .env && vim .env

必填：WX_APPID、WX_APPSECRET、JWT_SECRET（长随机串）、DATABASE_URL（含上一步密码）、AI_BASE_URL/AI_API_KEY。

4. 安装 + 迁移 + 启动

bash deploy/deploy.sh

脚本会：npm ci → npm run migrate 建表 → PM2 启动 → 打 /healthz 自检。 （若用 systemd：sudo cp deploy/labcalc-server.service /etc/systemd/system/ && sudo systemctl enable --now labcalc-server）

5. Caddy 反代（自动 HTTPS）

# 把 Caddyfile.snippet 内容追加到 /etc/caddy/Caddyfile，改好域名
sudo vim /etc/caddy/Caddyfile
sudo systemctl reload caddy

验证：curl https://labapi.你的备案域名/healthz 返回 200。

6. 小程序端接通

1. 微信公众平台 → 开发 → 开发管理 → 服务器域名 → request 合法域名加： https://labapi.你的备案域名
2. 前端 utils/api.js 把 BASE_URL 改成 https://labapi.你的备案域名，重新编译上传。

7. 验证全链路

• /healthz → capabilities 三项应为 true
• 小程序登录 → 看是否拿到 token
• 化合物搜索 → /api/compound?name=aspirin
• AI 问答 → /api/ai/ask

升级

cd /opt/labcalc-server && bash deploy/deploy.sh   # 幂等：拉取→依赖→迁移→重载→自检

回滚

git log --oneline           # 找上一个稳定 commit
git checkout <commit>
bash deploy/deploy.sh

注意

• .env 含密钥，已在 .gitignore，绝不提交；AppSecret 只存这里。
• 国内服务器访问 PubChem 可能慢/受限，compound_cache 表会缓存命中结果降低跨境请求。
• 备案未完成前，开发者工具可勾选「不校验合法域名」本地联调（前端 project.config.json 已设 urlCheck:false）。