docs: 补充部署示例、worktrees 设置并记录 T0.1 偏差

2026-09-30 05:50:37 +08:00
parent 27fccc2e2c
commit 86dc10a371
4 changed files with 105 additions and 1 deletions
@@ -0,0 +1,14 @@
+{
+  "setup-worktree-windows": [
+    "go mod download",
+    "if (Test-Path web/package.json) { pnpm --dir web install }"
+  ],
+  "setup-worktree-unix": [
+    "go mod download",
+    "if [ -f web/package.json ]; then pnpm --dir web install; fi"
+  ],
+  "setup-worktree": [
+    "go mod download",
+    "pnpm --dir web install"
+  ]
+}
@@ -0,0 +1,24 @@
+# 多阶段骨架：完整多架构发布见 Q4。
+# 语法阶段：Node 构建前端 → Go 编译（嵌入前端）→ distroless 运行。
+
+FROM node:24-bookworm AS web
+WORKDIR /src/web
+COPY web/package.json web/pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY web/ ./
+RUN pnpm build
+
+FROM golang:1.27-bookworm AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+COPY --from=web /src/web/dist ./web/dist
+ENV CGO_ENABLED=0
+RUN go build -tags embeddist -o /out/nixmsg ./cmd/nixmsg
+
+FROM gcr.io/distroless/static:nonroot
+COPY --from=build /out/nixmsg /nixmsg
+USER nonroot:nonroot
+ENTRYPOINT ["/nixmsg"]
+CMD ["serve"]
@@ -0,0 +1,31 @@
+listen: ":7443"                   # 端接入端口
+admin_listen: ""                  # 后台单独监听，如 "127.0.0.1:7444"；空表示后台也在 listen 上
+tls:
+  cert_file: ""
+  key_file: ""
+  allow_plaintext: false
+trusted_proxies: []               # 反向代理的地址段，如 ["127.0.0.1/32"]
+data_dir: "./data"
+limits:
+  max_body_bytes: 262144          # 只能调小
+  max_meta_bytes: 4096
+  max_frame_bytes: 786432
+  max_ttl_seconds: 2592000
+  max_schedule_seconds: 31536000
+  max_group_members: 1000
+  grace_seconds: 60
+  ack_timeout_seconds: 300
+  delivery_window: 32
+  receipt_window: 64
+  requests_per_second: 50         # 除 ack、receipt_ack 外，突发容量为 2 倍
+  max_pending_per_sender: 10000   # 等待发送或投递中的消息数，群消息算一条；0 表示不限
+  max_pending_per_receiver: 10000 # 排队未收下的投递数；0 表示不限
+session_idle_days: 30             # 会话令牌多少天没用就失效；0 表示不失效
+record_retention_days: 7          # 0 表示完成后不留记录
+idempotency_hours: 24
+receipt_retention_days: 7
+sqlite_synchronous: FULL          # 或 NORMAL
+metrics:
+  token: ""                       # 后台和端共用端口时，访问 /metrics 要带它；空表示共用端口时不提供
+log:
+  level: info
@@ -6,7 +6,42 @@

 ## 总控 L

-暂无。
+### T0.1 2026-09-30
+
+1. **前端嵌入方式**  
+   - 原条款：DEVELOPMENT 第 3 节 `web/embed.go` 用 `//go:embed all:dist`；TASKS T0.1；`.gitignore` 忽略 `web/dist`。  
+   - 实际做法：默认构建用 `-tags` 以外的 `embed_stub.go` 嵌入 `web/stub/`；`task build` 加 `-tags embeddist` 嵌入真实 `web/dist`。  
+   - 原因：`web/dist` 不进仓库，且要求没有前端产物时也能 `go build`。  
+   - 备选方案：提交最小 `dist`；或构建前脚本生成占位目录。  
+   - 影响：裸 `go build` 不含真实前端；正式产物必须走 `task build`。
+
+2. **listen.addr 写入时机**  
+   - 原条款：DEVELOPMENT 4.1「端口写 0 时」写 `<data_dir>/listen.addr`。  
+   - 实际做法：只要 `serve` 启动成功就写入实际监听地址。  
+   - 原因：测试启动器统一读取该文件更简单，固定端口场景也无害。  
+   - 备选方案：仅当配置端口为 0 时写入。  
+   - 影响：多一个小文件；行为超集，兼容文档要求。
+
+3. **迁移占位**  
+   - 原条款：T0.3 才写完整表与 `VACUUM INTO` 备份；T0.1 允许空执行器加空 0001。  
+   - 实际做法：`internal/store.Migrate` 建 `schema_migrations` 并应用 `0001_init.sql`（内容为 `SELECT 1;`）；不做迁移前备份。  
+   - 原因：保证 serve 可跑通迁移路径，表结构留给 T0.3。  
+   - 备选方案：完全空文件 + 只记版本。  
+   - 影响：T0.3 需替换 0001 正文并补备份逻辑；已应用的占位版本号仍为 1。
+
+4. **Taskfile 引入 taskfiles**  
+   - 原条款：TASKS T0.1 / 4.2 引入 `taskfiles/*.yml`。  
+   - 实际做法：`includes: '*': taskfile: taskfiles/*.yml, optional: true`，并放 `_init.yml` 占位。  
+   - 原因：空目录 glob 可能失败；各线稍后加自己的 yml。  
+   - 备选方案：主文件逐条 optional include 各线文件名。  
+   - 影响：无。
+
+5. **deploy/Dockerfile**  
+   - 原条款：完整多架构镜像属 Q4；T0.1 需要 `task docker` 目标。  
+   - 实际做法：提供单架构多阶段 Dockerfile 骨架，供 `task docker` 使用；T0.1 验证另用官方 `golang` 镜像跑 `task check`。  
+   - 原因：让 docker 目标可执行，又不抢 Q4 范围。  
+   - 备选方案：docker 目标仅 echo 提示。  
+   - 影响：镜像发布流程仍由 Q4 定稿。

 ## 平台 P