baa-conductor

T-008-ops-nginx.md

 1---
 2task_id: T-008
 3title: Nginx 与 VPS 运维
 4status: done
 5branch: feat/T-008-ops-nginx
 6repo: /Users/george/code/baa-conductor
 7base_ref: main
 8depends_on:
 9  - T-001
10write_scope:
11  - ops/nginx/**
12  - docs/ops/**
13updated_at: 2026-03-21
14---
15
16# T-008 Nginx 与 VPS 运维
17
18## 目标
19
20把设计里的二级域名、Nginx 转发、直连节点域名、Basic Auth 与运维说明落到可执行配置和文档中。
21
22## 本任务包含
23
24- 完成 `ops/nginx/baa-conductor.conf`
25- 补充 `includes/` 公共片段
26- 编写 VPS 部署说明
27- 明确 `conductor.makefile.so`、`mini-conductor.makefile.so`、`mac-conductor.makefile.so` 的配置关系
28
29## 本任务不包含
30
31- Cloudflare Worker 代码
32- launchd
33
34## 建议起始文件
35
36- `ops/nginx/baa-conductor.conf`
37- `ops/nginx/includes/common-proxy.conf`
38- `ops/nginx/includes/direct-node-auth.conf`
39- `docs/ops/README.md`
40- `DESIGN.md` 第 6、7 节
41
42## 交付物
43
44- 可执行或接近可执行的 Nginx 配置
45- VPS 运维说明
46
47## 验收
48
49- 包含统一入口
50- 包含直达 mini/mac
51- 包含 80 -> 443
52- 包含鉴权或保护建议
53
54## files_changed
55
56- `coordination/tasks/T-008-ops-nginx.md`
57- `docs/ops/README.md`
58- `ops/nginx/baa-conductor.conf`
59- `ops/nginx/includes/common-proxy.conf`
60- `ops/nginx/includes/direct-node-auth.conf`
61
62## commands_run
63
64- `git worktree add ../baa-conductor-T008 -b feat/T-008-ops-nginx main`
65- `command -v nginx`
66- `git diff --check -- ops/nginx docs/ops coordination/tasks/T-008-ops-nginx.md`
67- `rg -n "upstream conductor_primary|upstream mini_conductor_direct|upstream mac_conductor_direct|return 301 https://\\$host\\$request_uri|server_name conductor\\.makefile\\.so|server_name mini-conductor\\.makefile\\.so|server_name mac-conductor\\.makefile\\.so|ssl_certificate|auth_basic" ops/nginx/baa-conductor.conf ops/nginx/includes/direct-node-auth.conf`
68- `rg -n "conductor\\.makefile\\.so|mini-conductor\\.makefile\\.so|mac-conductor\\.makefile\\.so|nginx -t|htpasswd|80/tcp|443/tcp|4317" docs/ops/README.md`
69
70## result
71
72- `ops/nginx/baa-conductor.conf` 已补齐 3 个 upstream、统一 `80 -> 443` 跳转、3 个 TLS server block，以及统一入口与直连 mini/mac 的转发关系
73- `ops/nginx/includes/common-proxy.conf` 已补齐常用代理头、超时、request id、buffer 和 retry 配置
74- `ops/nginx/includes/direct-node-auth.conf` 已默认启用 Basic Auth，并补充可选 IP allowlist 的使用说明
75- `docs/ops/README.md` 已写明 VPS 部署、目录映射、证书准备、启用步骤、上线验证与保护建议
76
77## risks
78
79- 本机未安装 `nginx`，本次只完成静态合理性检查；上线前仍需在 VPS 上以真实证书和真实路径执行 `sudo nginx -t`
80- `100.71.210.78`、`100.112.239.13` 与 `4317` 端口来自当前设计文档，真实部署前应再次确认 Tailscale 地址和端口未变化
81- 若三域名经过 Cloudflare 代理，直连域名的 IP allowlist 需要先配置真实客户端 IP 恢复，否则 `allow/deny` 会基于 Cloudflare 出口 IP 生效
82
83## next_handoff
84
85- 把仓库中的 `ops/nginx/**` 同步到 VPS 的 `/etc/nginx/sites-available/` 与 `/etc/nginx/includes/baa-conductor/`
86- 准备 `.htpasswd` 与 TLS 证书后，在 VPS 上执行 `sudo nginx -t && sudo systemctl reload nginx`
87- 用 `curl` 验证统一入口的 `301/200`，以及 `mini-conductor.makefile.so`、`mac-conductor.makefile.so` 的 `401/200`
88
89## notes
90
91- `2026-03-21`: 创建任务卡