130 lines
5.9 KiB
Markdown
130 lines
5.9 KiB
Markdown
# 开发、生产环境与双部署方式实施计划
|
||
|
||
> **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`，精确推送并核对分支与标签。
|