feat(GOV-006): 建立环境配置与双部署基线

2026-08-13 10:54:55 +08:00
parent 4ce33d8c7d
commit 9203fdd0c2
43 changed files with 846 additions and 11 deletions
@@ -0,0 +1,9 @@
+# GitNexus 开发后结果
+
+- 执行：`npx gitnexus analyze`。
+- 工作区索引：620 个节点、651 条关系、7 个集群、0 条执行流程。
+- 增量分析：7 个已修改文件、25 个新增文件、0 个删除文件。
+- 当前索引提交：`4ce33d8`；配置和文档变化已进入增量图谱。
+- 状态：up-to-date。
+
+实现提交后再次分析并锚定最终提交。
@@ -0,0 +1,10 @@
+# GitNexus 前后对比
+
+| 项目 | 开发前 | 开发后工作区 | 变化 |
+|---|---:|---:|---:|
+| 节点 | 452 | 620 | +168 |
+| 关系 | 477 | 651 | +174 |
+| 集群 | 5 | 7 | +2 |
+| 执行流程 | 0 | 0 | 0 |
+
+新增集群来自环境模板与部署文档边界；没有生产执行流程变化，符合影响预估。
@@ -0,0 +1,8 @@
+# GitNexus 变更检测
+
+- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope staged`。
+- 最终暂存区：43 个文件、77 个符号。
+- 受影响流程：0。
+- 风险等级：低。
+
+范围包含配置模板、Compose、systemd、Nginx、部署文档、现行治理入口、契约测试和 GOV-006 档案。
@@ -0,0 +1,7 @@
+# GitNexus 开发前影响分析
+
+- 查询主题：`development production environment templates Docker Compose Ubuntu source deployment systemd`。
+- 关联范围：README、开发流程、开发规范、系统架构、GOV-005 和部署目录。
+- 本次新增配置、文档和静态测试，不修改既有生产函数、类或方法，无生产符号上游影响目标。
+- GitNexus 未识别业务执行流程；预计影响限于配置契约、部署边界和治理测试。
+- 风险控制：不提交真实秘密，不运行应用部署，不连接任何生产服务，明确示例骨架的未验证状态。
@@ -0,0 +1,129 @@
+# 开发、生产环境与双部署方式实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 建立可机器验证的开发/生产环境变量契约、本地 Redis Compose，以及 Docker Compose 与 Ubuntu 源码生产部署规范和配置骨架。
+
+**Architecture:** 八份 env 模板按进程和环境分离，但同一进程在 development/production 使用相同变量名。静态契约测试负责检查模板完整性、敏感值为空、Web 仅暴露 `VITE_*`、生产安全默认值和部署文件边界；当前应用尚未实现，不伪造可运行的应用镜像或启动命令。
+
+**Tech Stack:** dotenv 模板、Docker Compose、Redis、systemd、Nginx、Node.js 内置测试运行器、Markdown、GitNexus。
+
+## Global Constraints
+
+- 环境仅定义 `development` 与 `production`，生产禁止模拟数据、热更新和开发默认值回退。
+- 仓库提交八份 `*.env.example`，不提交任何真实 `.env` 或凭据。
+- 本地 Compose 只启动 Redis；Web/API/Scheduler/Worker 从源码运行。
+- 生产支持 Docker Compose 和 Ubuntu 22.04/24.04 x86_64 源码部署。
+- Node.js 22 LTS、pnpm 10、Nginx 和基础设施由管理员提供，项目只验证不安装。
+- 源码部署使用 `a-share` 用户和 `/etc/a-share-analysis/*.env`。
+- MySQL 与 RabbitMQ 第一阶段默认关闭；MySQL 条件配置遵守 GOV-005。
+
+---
+
+### Task 1: 建立失败的环境配置契约测试
+
+**Files:**
+- Create: `tools/governance/environment-baseline.test.mjs`
+- Modify: `package.json`
+
+**Interfaces:**
+- Consumes: `deploy/env/`、`deploy/compose/`、`deploy/systemd/`、`deploy/nginx/` 和 `docs/deployment/`。
+- Produces: `npm run test:environment-baseline`。
+
+- [ ] **Step 1: 编写模板和部署边界测试**
+
+测试八份模板存在、同一进程两环境键集合相同、敏感键为空、Web 仅含 `VITE_*`、生产安全开关正确、本地 Compose 仅定义 Redis，并检查 systemd/Nginx 与两份生产部署文档。
+
+- [ ] **Step 2: 验证测试因文件缺失而失败**
+
+运行：`npm run test:environment-baseline`
+
+预期：失败明确指出第一份缺少的环境模板或部署文件。
+
+### Task 2: 实现统一环境模板
+
+**Files:**
+- Create: `deploy/env/development/api.env.example`
+- Create: `deploy/env/development/scheduler.env.example`
+- Create: `deploy/env/development/worker.env.example`
+- Create: `deploy/env/development/web.env.example`
+- Create: `deploy/env/production/api.env.example`
+- Create: `deploy/env/production/scheduler.env.example`
+- Create: `deploy/env/production/worker.env.example`
+- Create: `deploy/env/production/web.env.example`
+- Modify: `.gitignore`
+
+**Interfaces:**
+- Consumes: GOV-006 设计中的变量作用域。
+- Produces: 后续 NestJS Schema 和部署方式共同使用的变量名契约。
+
+- [ ] **Step 1: 编写四类进程模板**
+
+每项变量附中文说明；敏感变量保持空值；MySQL/RabbitMQ/AI 由功能开关控制条件必填；生产值拒绝模拟数据和调试模式。
+
+- [ ] **Step 2: 加固忽略规则**
+
+只允许提交 `*.env.example`，忽略 `*.env.local`、真实 env 和本地运行目录。
+
+### Task 3: 实现本地 Redis 与生产部署骨架
+
+**Files:**
+- Create: `deploy/compose/development.yml`
+- Create: `deploy/compose/production.yml.example`
+- Create: `deploy/systemd/a-share-api.service.example`
+- Create: `deploy/systemd/a-share-scheduler.service.example`
+- Create: `deploy/systemd/a-share-worker.service.example`
+- Create: `deploy/nginx/a-share-analysis.conf.example`
+- Create: `docs/deployment/local-development.md`
+- Create: `docs/deployment/docker-compose-production.md`
+- Create: `docs/deployment/ubuntu-source-production.md`
+
+**Interfaces:**
+- Consumes: Task 2 的模板键集合。
+- Produces: 本地 Redis 启动入口、生产 Compose 配置边界、systemd EnvironmentFile 和 Nginx 代理示例。
+
+- [ ] **Step 1: 配置本地 Redis Compose**
+
+固定 Redis 镜像补丁版本，只暴露本机端口，使用项目专用容器名、网络、健康检查和仓库外本地数据目录；不得定义其他服务。
+
+- [ ] **Step 2: 配置生产部署骨架**
+
+生产 Compose 只表达应用服务的配置契约和不可变镜像要求；systemd 使用独立 EnvironmentFile，Nginx 托管静态文件并代理 `/api/`。
+
+- [ ] **Step 3: 编写开发与双生产部署文档**
+
+明确当前应用尚未脚手架化，文档只验证配置与部署边界；列出管理员前置条件、版本检查、健康检查、升级和回退规则。
+
+- [ ] **Step 4: 验证测试转绿**
+
+运行：`npm run test:environment-baseline && npm run test:mysql-baseline && npm run test:governance`
+
+预期：全部通过。Docker 可用时额外运行 `docker compose -f deploy/compose/development.yml config`。
+
+### Task 4: 完成现行规范、追溯与发布
+
+**Files:**
+- Modify: `docs/architecture/system-architecture.md`
+- Modify: `docs/governance/code-development-standards.md`
+- Modify: `docs/governance/development-workflow.md`
+- Modify: `README.md`
+- Modify: `docs/index.md`
+- Modify: `CHANGELOG.md`
+- Modify: `VERSION`
+- Create: GOV-006 除现有 `design.md`、`implementation-plan.md`、`gitnexus/before.md` 外的全部必备档案。
+
+**Interfaces:**
+- Consumes: 通过契约测试的配置与部署文件。
+- Produces: 可审查、可发布、可回退的 GOV-006 完整档案和 `v0.0.5`。
+
+- [ ] **Step 1: 更新架构和开发规范**
+
+记录环境模型、配置校验、两种部署方式、平台范围、管理员职责和生产防误用要求。
+
+- [ ] **Step 2: 执行 GitNexus、测试和双 Review**
+
+检测完整暂存区并运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
+
+- [ ] **Step 3: 中文提交、推送与发布**
+
+提交并推送 `main`；封存后创建带注释 `v0.0.5`，精确推送并核对分支与标签。
@@ -0,0 +1,17 @@
+id: GOV-006
+name: 开发、生产环境与双部署方式
+slug: environment-deployment-baseline
+status: verifying
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+code_review: review/code-review.md
+standards_review: review/standards-review.md
+implementation_commit: pending
+release: v0.0.5
@@ -0,0 +1,31 @@
+# 开发、生产环境与双部署方式 PRD
+
+- 功能编号：GOV-006
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 问题
+
+项目缺少开发/生产配置契约和部署边界，存在真实配置入库、生产误用模拟数据及两种部署方式行为漂移的风险。
+
+## 目标
+
+- 提供开发和生产的四类进程无秘密模板。
+- 本地只用 Compose 启动 Redis，应用从源码运行。
+- 同时规范 Docker Compose 与 Ubuntu 源码生产部署。
+- 生产配置严格校验且不随发布版本覆盖。
+
+## 非目标
+
+- 不安装服务器运行时或基础设施。
+- 不声称尚未实现的应用镜像、进程和健康端点已经可运行。
+- 不启用 MySQL、RabbitMQ、正式数据源或 AI。
+
+## 验收标准
+
+- 八份模板完整、跨环境键一致且无敏感值。
+- Web 模板只含公开 `VITE_*` 变量。
+- 开发 Compose 仅定义 Redis并可通过配置解析。
+- systemd、Nginx 和三份部署文档满足已确认平台与路径边界。
+- 环境契约测试完成红绿验证，双 Review 和治理门禁通过。
@@ -0,0 +1,16 @@
+# 测试结果
+
+## 测试先行证据
+
+新增环境基线测试后首次运行 6 个测试全部失败，分别指出八份模板、开发 Compose、systemd/Nginx 示例和部署文档不存在。
+
+补齐最小实现后：
+
+- 环境基线测试：6 个通过，0 个失败。
+- MySQL 基线测试：2 个通过，0 个失败。
+- 治理测试：5 个通过，0 个失败。
+- `docker compose -f deploy/compose/development.yml config`：通过，仅包含 Redis。
+- `git diff --check`：通过。
+- GitNexus 最终暂存区：43 个文件、77 个符号、0 条流程，风险为低。
+
+生产 Compose 和源码部署当前属于配置契约骨架，应用尚未脚手架化，因此没有伪造生产启动或健康检查成功证据。
@@ -0,0 +1,3 @@
+# 视觉验证
+
+本功能没有页面或交互变化，视觉验证不适用。
@@ -0,0 +1,8 @@
+# 发布说明
+
+## v0.0.5
+
+- 新增八份开发/生产无秘密环境模板。
+- 新增只启动 Redis 的本地开发 Compose。
+- 新增生产 Compose 契约骨架、systemd/Nginx 示例和 Ubuntu 源码部署规范。
+- 新增环境配置自动化契约测试。
@@ -0,0 +1,10 @@
+# 工程需求
+
+- 环境只定义 `development` 与 `production`。
+- API、Scheduler、Worker、Web 分别提供开发/生产模板，同进程键集合一致。
+- 敏感变量保持空值，真实配置被 Git 忽略。
+- 生产 Worker 固定 `MARKET_DATA_MODE=live`，第一阶段关闭 MySQL 与 RabbitMQ。
+- 本地 Compose 固定 Redis 补丁版本、仅绑定本机并提供健康检查。
+- Ubuntu 源码部署支持 22.04/24.04 LTS x86_64、Node.js 22 LTS、pnpm 10。
+- systemd 使用 `a-share` 用户及独立 `EnvironmentFile`；Nginx 托管静态文件并代理 API。
+- 生产 Compose 使用不可变镜像和外部 env，不承诺当前骨架可直接上线。
@@ -0,0 +1,27 @@
+# 配置与文档 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 基线提交：`0328f9e`
+- 设计提交：`fa1df71`
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## 审查结论
+
+八份模板保持跨环境键一致，敏感值为空，Web 只含公开变量；开发 Compose 只启动 Redis；生产部署示例明确为未验证骨架。现行架构和规范覆盖启动校验、防误用与管理员职责。
+
+## 发现与处置
+
+| 严重程度 | 发现 | 处置 |
+|---|---|---|
+| Important | 两种部署方式可能形成不同变量协议 | 强制复用同一模板键并用自动测试比较 |
+| Important | 示例容易被误认为可直接上线 | Compose 和文档显式标记需在应用脚手架后验证 |
+| Important | 前端变量可能泄露服务端秘密 | 测试要求 Web 模板每个键都以 `VITE_` 开头且只含公开值 |
+| Minor | 本地 Redis 数据可能进入仓库 | 使用 `.local/redis` 并加固忽略规则 |
+
+- 环境契约测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
+- Docker Compose 配置解析成功且只包含 Redis。
+- GitNexus 最终暂存区检测为 43 个文件、77 个符号、0 条流程、低风险。
+
+最终结论：passed
@@ -0,0 +1,21 @@
+# 开发规范符合性 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 实现提交：`pending`
+- 日期：2026-08-13
+
+## 检查结果
+
+- [x] 设计经用户确认后实施。
+- [x] 环境契约先有 6 个失败测试，再补实现使其通过。
+- [x] 模板无真实秘密，真实 env 与本地数据被忽略。
+- [x] 不连接或探测生产服务，不安装服务器软件。
+- [x] MySQL 变量符合 GOV-005，第一阶段默认关闭。
+- [x] Docker Compose 与源码部署共享变量契约。
+- [x] 未把尚未实现的应用描述为已可部署。
+- [x] 无界面变化，视觉验证合理标记不适用。
+
+没有未解决的 Critical 或 Important 不符合项。
+
+最终结论：passed
@@ -0,0 +1,5 @@
+# 回退说明
+
+本功能没有部署应用或连接生产服务。若配置规范需要修正，使用新的中文修复提交更新模板、文档和测试，不移动共享标签。
+
+开发 Redis 数据位于被忽略的 `.local/redis/`，版本回退不得自动删除该目录。生产真实 env 位于仓库外，不随应用版本切换覆盖。
@@ -0,0 +1,8 @@
+# 测试计划
+
+- 先运行环境基线测试，证明六类行为因模板和部署文件缺失而失败。
+- 实现后要求环境测试 6/6、MySQL 基线 2/2、治理测试 5/5 通过。
+- 运行 Docker Compose 配置解析，确认只有 Redis。
+- 运行 `git diff --check`、敏感信息扫描和 GitNexus 最终暂存区检测。
+- 运行 `npm run governance:finish -- GOV-006 environment-deployment-baseline`。
+- 本功能无页面变化，视觉验证不适用。