# Server B Web 运行时 Runbook

本文记录 S05 在 Server B 上建立的 Node.js、pnpm、Nginx、systemd 与开发 TLS 基线。当前环境是本地 KVM 开发环境，不是阿里云生产环境。

## 1. 固定版本

| 组件 | 版本 | 管理方式 |
| --- | --- | --- |
| Node.js | `v22.22.2` / Debian 包 `22.22.2-1nodesource1` | NodeSource 22.x，`apt-mark hold` |
| Corepack | `0.34.6` | Node 全局工具 |
| pnpm | `10.33.0` | 全局固定版本；项目应再用 `packageManager` 固定 |
| Nginx | `1.24.0-2ubuntu7.12` | Ubuntu 24.04 security/updates，`apt-mark hold` |

Node.js 22 当前属于 LTS 线。固定包在升级前必须先核对 Node/Nginx 安全公告、NestJS/Prisma 兼容性并完成回归测试。

版本记录：`/etc/lisglosips/web-runtime-versions.env`。

## 2. 目录与发布模型

```text
/opt/lisglosips/
├── releases/
│   └── s05-placeholder-20260620/
│       ├── public/index.html
│       └── server.mjs
└── current -> /opt/lisglosips/releases/s05-placeholder-20260620
```

- 发布目录由 `root:lisglosips` 持有，程序只读。
- `current` 必须是指向完整 release 的符号链接。
- 正式发布先写入新 release，完成校验后再原子切换 `current`。
- 不允许直接在 `current` 指向的 release 内在线修改代码。
- systemd 可写状态目录为 `/var/lib/lisglosips`，运行目录为 `/run/lisglosips`。

## 3. systemd 服务模板

模板：`/etc/systemd/system/lisglosips@.service`。

实例环境文件：`/etc/lisglosips/<实例名>.env`，权限必须为 `0640 root:lisglosips`。当前实例：

```text
lisglosips@api.service -> /etc/lisglosips/api.env
```

模板默认使用 `lisglosips` 系统用户，启用只读系统、私有临时目录、空 capability、设备隔离和内核保护。后续 Worker 如需写录音目录，应使用实例 drop-in 精确增加 `ReadWritePaths`，不要放宽整个模板。

常用命令：

```bash
sudo systemctl status lisglosips@api
sudo systemctl restart lisglosips@api
sudo journalctl -u lisglosips@api -n 100 --no-pager
sudo systemd-analyze security lisglosips@api.service
```

## 4. Nginx 路由

| 路径 | 行为 |
| --- | --- |
| `/` | `/opt/lisglosips/current/public` 静态站点，支持 SPA fallback |
| `/healthz` | 反向代理到 `127.0.0.1:3000` |
| `/api/` | API 代理，单 IP `20 r/s`、burst 40 |
| `/api/auth/login` | 登录专用限制，单 IP `5 r/min`、burst 3 |
| `/_recordings/` | 仅供 `X-Accel-Redirect` 内部访问，外部请求返回 404 |

关键文件：

```text
/etc/nginx/conf.d/lisglosips-global.conf
/etc/nginx/sites-available/lisglosips.conf
/etc/nginx/snippets/lisglosips-proxy.conf
/etc/nginx/snippets/lisglosips-security-headers.conf
/etc/nginx/snippets/lisglosips-tls.conf
```

应用仅监听 `127.0.0.1:3000`。Nginx 监听 80/443，但 nftables 仅允许已登记管理端访问 443；开发阶段没有对外开放 80。

配置变更：

```bash
sudo nginx -t
sudo systemctl reload nginx
```

## 5. 开发 TLS

开发 CA 和证书位于：

```text
/etc/lisglosips/pki/ca/lisglosips-dev-ca.crt
/etc/lisglosips/pki/ca/lisglosips-dev-ca.key
/etc/lisglosips/pki/certs/server.crt
/etc/lisglosips/pki/private/server.key
```

CA 私钥为 `0600 root:root`，服务器私钥为 `0640 root:www-data`。证书 SAN 包含 `lisglosips.local`、`yanzi`、`100.90.90.91` 和 `127.0.0.1`。

重新签发开发证书：

```bash
sudo /usr/local/sbin/lisglosips-issue-dev-cert
sudo nginx -t
sudo systemctl reload nginx
```

本机公有 CA 副本保存在 `.codex-private/tls/lisglosips-dev-ca.crt`，不得把 CA 私钥复制出 Server B。Windows 使用私有 CA 测试时，因开发 CA 不发布 CRL，curl 需附加 `--ssl-no-revoke`；这不会关闭证书链、主机名或签名校验。

迁移阿里云后必须替换为正式域名证书，并完成：

1. 把证书和私钥放入受控 Secret 路径。
2. 更新 `lisglosips-tls.conf`。
3. 将 HSTS 从开发值 `300` 调整为生产值，建议先观察再提升至 `31536000`。
4. 验证自动续期、续期失败告警和回滚证书。
5. 开放 80 仅用于 ACME/跳转，或使用 DNS-01 后继续关闭 80。

## 6. 健康检查

```bash
curl --fail http://127.0.0.1:3000/healthz
curl --fail --cacert /etc/lisglosips/pki/ca/lisglosips-dev-ca.crt \
  https://127.0.0.1/healthz
sudo ss -lntp | grep -E ':(80|443|3000)\b'
sudo systemctl --failed
```

预期：

- `/healthz` 返回 `status=ok`。
- 3000 仅出现在 `127.0.0.1`。
- 443 由 Nginx 监听。
- 首页响应包含 HSTS、CSP、X-Frame-Options、X-Content-Type-Options 和 Permissions-Policy。
- TLS 1.2/1.3 可用，TLS 1.1 被拒绝。

## 7. 新版本发布

```bash
release="2026xxxxTxxxxxxZ"
sudo install -d -o root -g lisglosips -m 0750 "/opt/lisglosips/releases/$release"
# 将已经构建和校验的产物放入新 release。
sudo chown -R root:lisglosips "/opt/lisglosips/releases/$release"
sudo find "/opt/lisglosips/releases/$release" -type d -exec chmod 0750 {} +
sudo find "/opt/lisglosips/releases/$release" -type f -exec chmod 0640 {} +
sudo ln -sfn "/opt/lisglosips/releases/$release" /opt/lisglosips/current
sudo systemctl restart lisglosips@api
sudo nginx -t && sudo systemctl reload nginx
```

发布后必须检查内部健康、HTTPS 健康、日志、应用端口监听和前端静态文件。数据库迁移从 S08 起必须在切换 `current` 前按迁移 Runbook 执行。

## 8. 回滚

应用回滚：把 `current` 指回上一 release，重启应用并检查 HTTPS 健康。

```bash
sudo ln -sfn /opt/lisglosips/releases/<previous> /opt/lisglosips/current
sudo systemctl restart lisglosips@api
```

S05 变更前备份：

```text
/var/backups/lisglosips-s05/20260620T123432Z
```

其中 `pre-change.tar.gz` 包含变更前应用与配置，`SHA256SUMS` 用于恢复前校验。恢复 Nginx/systemd 配置后必须执行 `nginx -t`、`systemctl daemon-reload`，再重启对应服务。卸载 Nginx或解除包固定不是常规回滚动作，只有确认恢复目标需要时才执行。

## 9. 已知事项

- NodeSource 仓库在本地代理链路上偶尔出现 TLS 握手中断；现有索引和已安装包可用。升级前必须先确认仓库恢复并校验候选版本。
- 当前证书仅供开发，不能用于阿里云生产。
- 80 已监听但被 nftables 拒绝；生产是否开放取决于证书签发方案。
- 当前 API 是 S05 无依赖占位服务，S07 后端骨架完成后替换。