293 lines
9.6 KiB
Markdown
293 lines
9.6 KiB
Markdown
# Multi-Address Single Deployment Data Implementation Plan
|
||
|
||
> **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:** Ensure external and local/LAN access addresses are documented and verified as multiple entrypoints to the same deployment stack and database, not two separately running data sets.
|
||
|
||
**Architecture:** The application keeps one active Compose stack for formal business data. External and local addresses both route to that stack's Nginx, which forwards `/api/` to the same NestJS server and PostgreSQL volume. `docker-compose.local.yml` remains an independent local/LAN demo stack and must not be described as a synced copy of production data.
|
||
|
||
**Tech Stack:** Docker Compose, Nginx reverse proxy template, Next.js same-origin API config, Node deployment verifier, Markdown deployment docs.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
- Modify `scripts/verify-production-deploy.mjs`: add checks that deployment docs and env examples describe multi-address single-stack behavior.
|
||
- Modify `.env.production.example`: add comments that `SERVER_NAME` is the primary public host and local/LAN access must route to the same Nginx stack.
|
||
- Modify `.env.local-server.example`: add comments that this is an independent local/LAN demo stack, not a synced view of production data.
|
||
- Modify `docs/deployment.md`: explain the recommended multi-address single deployment and warn against running prod/local stacks for the same business.
|
||
- Modify `docs/architecture.md`: document that one formal business stack may have multiple access addresses.
|
||
- Modify `docs/decisions.md`: add a decision that address-level consistency is solved by one active deployment stack, not data sync.
|
||
- Modify `docs/workflow.md`: update deployment flow and troubleshooting checks for address routing.
|
||
|
||
---
|
||
|
||
### Task 1: Add Deployment Verifier Expectations
|
||
|
||
**Files:**
|
||
- Modify: `scripts/verify-production-deploy.mjs`
|
||
|
||
- [ ] **Step 1: Add failing verifier snippets**
|
||
|
||
In `scripts/verify-production-deploy.mjs`, update existing checks so the deployment verifier requires the new wording.
|
||
|
||
Add these snippets to the `.env.production.example` check:
|
||
|
||
```js
|
||
'Primary public host',
|
||
'same Compose Nginx',
|
||
```
|
||
|
||
Add these snippets to the `.env.local-server.example` check:
|
||
|
||
```js
|
||
'independent local/LAN demo stack',
|
||
'does not sync with production data',
|
||
```
|
||
|
||
Add these snippets to the `docs/deployment.md` check:
|
||
|
||
```js
|
||
'同一部署多入口访问',
|
||
'外网地址和本地地址',
|
||
'同一套 Compose',
|
||
'不要同时启动',
|
||
```
|
||
|
||
Add these snippets to the `docker-compose.prod.yml` check:
|
||
|
||
```js
|
||
'SERVER_NAME',
|
||
'NEXT_PUBLIC_API_URL',
|
||
```
|
||
|
||
Keep all existing checks that still apply.
|
||
|
||
- [ ] **Step 2: Run verifier to confirm it fails**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
pnpm deploy:verify
|
||
```
|
||
|
||
Expected: command exits non-zero and prints missing snippets for `.env.production.example`, `.env.local-server.example`, and `docs/deployment.md`.
|
||
|
||
- [ ] **Step 3: Commit failing verifier**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git add scripts/verify-production-deploy.mjs
|
||
git commit -m "test(deploy): 覆盖多入口单部署校验"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Clarify Environment Examples
|
||
|
||
**Files:**
|
||
- Modify: `.env.production.example`
|
||
- Modify: `.env.local-server.example`
|
||
|
||
- [ ] **Step 1: Update production env comments**
|
||
|
||
In `.env.production.example`, replace:
|
||
|
||
```env
|
||
# Public entrypoint
|
||
SERVER_NAME=pm.example.com
|
||
```
|
||
|
||
with:
|
||
|
||
```env
|
||
# Public and local entrypoints
|
||
# Primary public host. Local/LAN addresses should route to the same Compose Nginx stack,
|
||
# not to a separate docker-compose.local.yml stack, when they need the same business data.
|
||
SERVER_NAME=pm.example.com
|
||
```
|
||
|
||
Keep `NEXT_PUBLIC_API_URL=/api/v1`.
|
||
|
||
- [ ] **Step 2: Update local-server env comments**
|
||
|
||
In `.env.local-server.example`, replace:
|
||
|
||
```env
|
||
# Copy to .env.local-server for an all-in-one local/LAN deployment.
|
||
```
|
||
|
||
with:
|
||
|
||
```env
|
||
# Copy to .env.local-server for an independent local/LAN demo stack.
|
||
# This stack uses local_* volumes and does not sync with production data.
|
||
# If external and local addresses must show the same business data, route both addresses to the same production Compose stack instead.
|
||
```
|
||
|
||
- [ ] **Step 3: Run verifier to confirm docs still fail**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
pnpm deploy:verify
|
||
```
|
||
|
||
Expected: command still exits non-zero because `docs/deployment.md` has not yet been updated.
|
||
|
||
- [ ] **Step 4: Commit env comments**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git add .env.production.example .env.local-server.example
|
||
git commit -m "docs(deploy): 标注本地栈不与生产数据同步"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Update Deployment And Architecture Docs
|
||
|
||
**Files:**
|
||
- Modify: `docs/deployment.md`
|
||
- Modify: `docs/architecture.md`
|
||
- Modify: `docs/decisions.md`
|
||
- Modify: `docs/workflow.md`
|
||
|
||
- [ ] **Step 1: Add deployment section for multi-address access**
|
||
|
||
In `docs/deployment.md`, add this section before “本地服务器部署”:
|
||
|
||
````markdown
|
||
## 同一部署多入口访问
|
||
|
||
如果只是希望外网地址和本地地址看到同一份业务数据，不要启动两套部署栈。正确方式是让外网域名、公网 IP、内网 IP 或本机地址都进入同一套 Compose 的 Nginx。
|
||
|
||
```text
|
||
外网地址和本地地址
|
||
-> 同一套 Compose Nginx
|
||
-> 同一个 web/server
|
||
-> 同一个 PostgreSQL volume
|
||
```
|
||
|
||
生产同域部署保持：
|
||
|
||
```env
|
||
NEXT_PUBLIC_API_URL=/api/v1
|
||
```
|
||
|
||
这样浏览器从哪个地址打开页面，就请求该地址下的 `/api/v1`。只要这些地址最终进入同一个 Nginx/server，数据就是同一份。
|
||
|
||
不要同时启动 `docker-compose.prod.yml` 和 `docker-compose.local.yml` 来承载同一套正式业务。它们使用不同 volume，会看到两套数据。
|
||
````
|
||
|
||
Use the four-backtick outer fence shown above if copying this plan into another Markdown document, because the section contains nested fences.
|
||
|
||
- [ ] **Step 2: Clarify local-server deployment is independent**
|
||
|
||
In `docs/deployment.md`, under “本地服务器部署”, add this paragraph near the top:
|
||
|
||
```markdown
|
||
本地服务器部署是一套独立 local/LAN 演示栈，使用 `local_*` volumes。它适合办公室内网试用或离线演示，不会与云服务器生产数据自动保持一致。如果目标是外网地址和本地地址看到同一份正式业务数据，请使用上面的“同一部署多入口访问”，而不是同时运行两套栈。
|
||
```
|
||
|
||
- [ ] **Step 3: Update architecture production boundary**
|
||
|
||
In `docs/architecture.md`, under the production deployment layer, add:
|
||
|
||
```markdown
|
||
同一套正式业务部署可以有多个访问入口，例如外网域名、公网 IP、内网 IP 或本机地址。多入口必须进入同一个 Nginx/server/PostgreSQL 栈，才能看到同一份数据。`docker-compose.local.yml` 是独立本地/LAN 演示栈，不能作为生产栈的数据同步副本。
|
||
```
|
||
|
||
- [ ] **Step 4: Add decision record**
|
||
|
||
In `docs/decisions.md`, append a new decision:
|
||
|
||
```markdown
|
||
## 40. 外网与本地访问地址通过同一部署栈保持数据一致
|
||
|
||
**问题**：用户希望外网地址和本地/内网地址访问系统时看到同一份业务数据。如果两个地址分别打到 `docker-compose.prod.yml` 和 `docker-compose.local.yml`，就会使用不同 PostgreSQL volume，数据天然分叉。
|
||
|
||
**决策**：外网地址和本地地址应作为同一套正式业务部署的多个入口，全部路由到同一个 Nginx/server/PostgreSQL 栈。`docker-compose.local.yml` 只用于独立本地/LAN 演示，不承诺与生产数据一致。
|
||
|
||
**理由**：这是访问入口问题，不是数据同步问题。保持单部署栈可以复用现有 `/api/v1` 同域配置和 `app_data` 乐观锁，避免引入双向同步、冲突合并和数据库复制复杂度。
|
||
```
|
||
|
||
- [ ] **Step 5: Update workflow deployment flow**
|
||
|
||
In `docs/workflow.md`, in the production deployment flow, add:
|
||
|
||
```markdown
|
||
外网地址和本地地址要看到同一份数据时，必须让两个地址都进入同一套 Compose/Nginx。不要同时用 `docker-compose.prod.yml` 和 `docker-compose.local.yml` 承载同一套业务；本地栈使用 `local_*` volumes，只适合独立演示。
|
||
```
|
||
|
||
Also add this troubleshooting item:
|
||
|
||
```markdown
|
||
如果外网地址和本地地址数据不一致，先检查两个地址是否打到了同一个 `/api/v1/config/ai` 后端和同一个 Compose project；不要先做数据库同步。
|
||
```
|
||
|
||
- [ ] **Step 6: Run verifier and type checks**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
pnpm deploy:verify
|
||
pnpm --filter web type-check
|
||
pnpm --filter server type-check
|
||
```
|
||
|
||
Expected:
|
||
|
||
- `pnpm deploy:verify` prints `Production deployment artifacts verified.`
|
||
- Both type-check commands exit 0.
|
||
|
||
- [ ] **Step 7: Commit docs**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git add docs/deployment.md docs/architecture.md docs/decisions.md docs/workflow.md
|
||
git commit -m "docs(deploy): 说明多入口访问同一部署数据"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Final Verification And Reporting
|
||
|
||
**Files:**
|
||
- No file changes expected.
|
||
|
||
- [ ] **Step 1: Run final verification**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
pnpm deploy:verify
|
||
pnpm --filter web type-check
|
||
pnpm --filter server type-check
|
||
git status --short
|
||
```
|
||
|
||
Expected:
|
||
|
||
- `pnpm deploy:verify` exits 0.
|
||
- `pnpm --filter web type-check` exits 0.
|
||
- `pnpm --filter server type-check` exits 0.
|
||
- `git status --short` shows only intentional plan/spec files if they were not committed, otherwise no output.
|
||
|
||
- [ ] **Step 2: Report operational guidance**
|
||
|
||
In the final response, include:
|
||
|
||
```text
|
||
外网地址和本地地址要看同一份数据时，只运行一套正式业务 Compose；让所有地址都反代到同一个 Nginx/server/PostgreSQL。
|
||
```
|
||
|
||
Also include:
|
||
|
||
```text
|
||
docker-compose.local.yml 是独立演示栈；如果同时和生产栈运行，会看到两套数据。
|
||
```
|