@@ -0,0 +1,667 @@
# P1 prod 写侧可用 实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标： ** 让 prod profile 在本机 compose 内具备完整写侧与游玩链路（上传/投稿/审核/virtual 子域运行时），并收掉 `POSTGRES_PASSWORD` 默认值。
**架构： ** 方案 A（镜像 dev 直连法）——新增 `minio-prod` （主机 9001，浏览器跨源直连），`api-prod` 补 `STORAGE_S3_*` /`GAMES_BASE_DOMAIN` /`CORS_ALLOWED_ORIGINS` ； `crearte` 的 nginx 配置改为 envsubst 模板，通配游戏域块参数化并补 `/api/` 同源反代；TLS 本轮不做。
**技术栈： ** docker compose v5、nginx:1.27-alpine entrypoint envsubst 模板、Go CLI（容器内 `/app/crearte-server` ）、curl+python3 冒烟链。
**依据： ** `docs/specs/2026-09-29-prod-write-side-design.md` （已批准）。规格覆盖映射见文末自检。
---
## 环境事实（本机，worker 必读）
- 仓库布局：wrapper `crearte-monorepo/` 下平级 `crearte` 、`crearte-server` 、`crearte-deploy` （已 clone，全在 master 干净）。
- 本机 `crearte-deploy/.env` **不存在 ** ， `docker volume ls` **无任何 crearte 卷 ** （全新环境，无旧数据迁移负担；口令迁移警告仍要写 README，供其他主机用）。
- 本机无 host node/go。前端测试一律容器内跑，镜像 `crearte:dev` 需先由 compose 构建（任务 2）。
- `git@github.com` SSH 认证 = XingfenD（可推 crearte/crearte-deploy）；wrapper remote = `git@git.yoresee.cc:XingfenD/crearte-monorepo.git` 。各仓若报 `Author identity unknown` ： `git config user.name XingfenD && git config user.email xingfen.fendy@outlook.com` （
- 主机端口 8080/9000/9001/5432/5434 当前均空闲。`*.localhost` 由 Chrome 内建解析、glibc 不保证——curl 一律加 `--resolve <sub>.localhost:8080:127.0.0.1` 。
- compose `:?` 守卫在 config 期对整个文件生效（不分 profile）：任何 `--profile X config -q` 都要求 `.env` 五项 secret 齐（POSTGRES_PASSWORD/MINIO_ROOT_USER/MINIO_ROOT_PASSWORD/AUTH_TOKEN_SECRET/BUNDLE_KEK_k1）。
## 文件结构
| 仓 | 文件 | 动作 | 职责 |
|---|---|---|---|
| crearte | `deploy/nginx.conf.template` | 新建（git mv 改名 + 编辑） | 两 server 块的 envsubst 模板：`_` 主站 + `${GAMES_SERVER_NAME}` 通配游戏域（含新 `/api/` 反代） |
| crearte | `deploy/Dockerfile` | 修改 L15 | COPY 指向模板目录 |
| crearte | `src/scripts/repo-yaml.test.ts` | 修改 describe 块 | 守卫测试同步读模板、新增 `/api/` 断言 |
| crearte | `src/scripts/dev-game-runtime.ts` | 修改 L2 注释 | 引用路径改为 .template |
| crearte | `docs/CHANGELOG.md` | 顶部加 0.15.0 | 变更账目 |
| crearte-deploy | `docker-compose.yml` | 修改 | minio-prod、api-prod 写侧 env、web-prod args/env、口令去默认、新卷 |
| crearte-deploy | `.env.example` | 重写（全文件） | secret 占位与新变量注释 |
| crearte-deploy | `README.md` | 增 prod 小节 + 迁移警告 + 真机 TLS 清单 | 用法与数据 |
| crearte-deploy | `docs/CHANGELOG.md` | 顶部加 0.5.0 | 变更账目 |
| wrapper | `docs/ROADMAP.md` 、`docs/CHANGELOG.md` 、本计划索引 | 修改 | 状态与账目 |
提交顺序（spec §7）：crearte → crearte-deploy → wrapper。
---
### 任务 1： ）
**分支： ** `cd crearte && git checkout -b feat/prod-nginx-wildcard-api`
- [ ] **步骤 1.1：改写守卫测试（先红） **
`src/scripts/repo-yaml.test.ts` ：将整个 `describe('deploy/nginx.conf', ...)` 块替换为：
``` ts
describe ( 'deploy/nginx.conf.template' , ( ) = > {
async function loadTemplate ( ) : Promise < string > {
return readFile ( path . join ( REPO_ROOT , 'deploy' , 'nginx.conf.template' ) , 'utf8' )
}
it ( '通配游戏域 server block 暴露运行时三件套、/api/ 同源反代与 404 兜底' , async ( ) = > {
const wildcard = serverBlock ( await loadTemplate ( ) , '${GAMES_SERVER_NAME}' )
expect ( wildcard ) . toMatch ( /listen\s+80;/ )
expect ( wildcard ) . toMatch ( /root\s+\/usr\/share\/nginx\/html;/ )
const exact = [ . . . wildcard . matchAll ( /location\s*=\s*(\S+)\s*\{([^}]*)\}/g ) ]
expect ( exact . map ( ( [ , location ] ) = > location ) . sort ( ) ) . toEqual ( [ '/__bootstrap' , '/agent.js' , '/sw.js' ] )
for ( const [ , location , body ] of exact ) {
expect ( body , ` ${ location } 需要 no-store ` ) . toContain ( '"no-store"' )
}
const api = wildcard . match ( /location\s+\/api\/\s*\{([^}]*)\}/ )
expect ( api , '通配块缺少 /api/ 反代（子域运行时取钥依赖同源代理）' ) . toBeTruthy ( )
expect ( api ? . [ 1 ] ) . toMatch ( /proxy_pass\s+http:\/\/\$api_upstream;/ )
expect ( api ? . [ 1 ] ) . toMatch ( /set\s+\$api_upstream\s+api:8080;/ )
expect ( wildcard ) . toMatch ( /location\s*\/\s*\{[\s\S]*?return 404;\s*\}/ )
expect ( wildcard ) . not . toMatch ( /location\s+\/data\// )
expect ( wildcard ) . not . toMatch ( /location\s+\/assets\// )
} )
it ( '主站为 /data/bundles/ 提供 CORS 且保留 /data/ 行为' , async ( ) = > {
const main = serverBlock ( await loadTemplate ( ) , '_' )
const bundles = main . match ( /location\s+\/data\/bundles\/\s*\{([^}]*)\}/ )
expect ( bundles , '主站缺少 /data/bundles/ location' ) . toBeTruthy ( )
expect ( bundles ? . [ 1 ] ) . toContain ( 'Access-Control-Allow-Origin' )
expect ( bundles ? . [ 1 ] ) . toMatch ( /try_files\s+\$uri\s+=404;/ )
expect ( main ) . toMatch ( /location\s+\/data\/\s*\{/ )
} )
} )
```
> `serverBlock()` 的 `server_name ${serverName};` 拼接传入字符串 `'${GAMES_SERVER_NAME}'` 后得到 `server_name ${GAMES_SERVER_NAME};`，与模板文本逐字匹配；JS 模板不会对已插值的 `$` 二次展开。
- [ ] **步骤 1.2：跑测试确认红 **
``` bash
cd crearte && npx --yes vitest run src/scripts/repo-yaml.test.ts
```
预期：FAIL（ `ENOENT ... deploy/nginx.conf.template` 或 serverBlock 抛「缺少 server_name」）。**若本机 npx 因 node_modules 缺失失败，推迟到步骤 1.5 用容器跑，同样先确认红再继续。**
- [ ] **步骤 1.3：git mv 改名并编辑模板 **
``` bash
cd crearte && git mv deploy/nginx.conf deploy/nginx.conf.template
```
将文件整体重写为以下内容（头部注释为新增；通配块 `server_name` 参数化并新增 `/api/` location；其余与旧文件逐字一致）：
``` nginx
# envsubst 模板：nginx 官方镜像 entrypoint（
# 渲染到 /etc/nginx/conf.d/default.conf。$uri/$host/$api_upstream 等 nginx 内建变量不是
# 环境变量，原样保留。运行期唯一必须定义的变量：GAMES_SERVER_NAME（
server {
listen 80 ;
server_name _ ;
root /usr/share/nginx/html ;
index index.html ;
gzip on ;
gzip_types text/css application/javascript application/json image/svg+xml ;
gzip_min_length 1024 ;
location = /index.html {
add_header Cache-Control "no-cache" ;
}
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable" ;
try_files $uri = 404 ;
}
location /data/bundles/ {
add_header Cache-Control "no-cache" ;
add_header Access-Control-Allow-Origin "*" ;
try_files $uri = 404 ;
}
location /data/ {
add_header Cache-Control "no-cache" ;
try_files $uri = 404 ;
}
location /api/ {
resolver 127.0.0.11 valid=10s ;
set $api_upstream api : 8080 ;
proxy_pass http:// $api_upstream ;
proxy_set_header Host $host ;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
}
location / {
try_files $uri /index.html ;
}
}
server {
listen 80 ;
server_name ${GAMES_SERVER_NAME} ;
root /usr/share/nginx/html ;
location = /__bootstrap {
add_header Cache-Control "no-store" ;
try_files /bootstrap/index.html = 404 ;
}
location = /sw.js {
add_header Cache-Control "no-store" ;
try_files /sw.js = 404 ;
}
location = /agent.js {
add_header Cache-Control "no-store" ;
try_files /agent.js = 404 ;
}
# 子域游玩时 sw/agent 取 bundle-key 走同源反代（prod 由本块承担；dev 等价逻辑在 vite 插件）
location /api/ {
resolver 127.0.0.11 valid=10s ;
set $api_upstream api : 8080 ;
proxy_pass http:// $api_upstream ;
proxy_set_header Host $host ;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
}
location / {
return 404 ;
}
}
```
- [ ] **步骤 1.4：改 Dockerfile 与过时注释 **
`deploy/Dockerfile` L15：
``` dockerfile
# 旧：COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
COPY deploy/nginx.conf.template /etc/nginx/templates/default.conf.template
```
`src/scripts/dev-game-runtime.ts` L2 注释：`（ ） → `（ ） 。
- [ ] **步骤 1.5：容器内跑全量单测确认绿（含类型） **
先建镜像与依赖卷（在 deploy 目录，context 会用到当前分支工作树）：
``` bash
cd ../crearte-deploy
docker compose --profile mock build mock # 产出 crearte:dev
docker run --rm -v " $PWD /../crearte " :/repo \
-v crearte-deploy_mock_node_modules:/repo/src/node_modules \
-w /repo/src crearte:dev npm test
```
预期：全部 PASS（含 `repo-yaml.test.ts` ；必须挂整个 crearte 仓，只挂 `src/` 会假失败——HANDOFF 既有事实）。再：
``` bash
docker run --rm -v " $PWD /../crearte " :/repo \
-v crearte-deploy_mock_node_modules:/repo/src/node_modules \
-w /repo/src crearte:dev npm run typecheck
```
预期：无错误。
- [ ] **步骤 1.6： **
`crearte/docs/CHANGELOG.md` 顶部（`## [0.14.0]` 之前）插入（英中行相邻、条间空行）：
``` markdown
## [0.15.0] - 2026-09-29
### Changed / 变更
- `deploy/nginx.conf` became `deploy/nginx.conf.template` , rendered at container start by the official nginx entrypoint's envsubst pass (`/etc/nginx/templates/` ). The wildcard game server's `server_name` is now the `GAMES_SERVER_NAME` variable instead of the hardcoded `*.games.example.com` , and the block gained `location /api/` same-origin reverse proxy to `api:8080` — without it, prod play runtime on `<sub>.<domain>` couldn't reach bundle-key (dev only worked because vite proxies `/api` on every host). The three-piece runtime (`/__bootstrap` , `/sw.js` , `/agent.js` ) and the 404 fallback are unchanged; the shape is pinned by `repo-yaml.test.ts` against the template.
- `deploy/nginx.conf` 改为 `deploy/nginx.conf.template` ，由 nginx 官方镜像 entrypoint 的 envsubst 机制在容器启动时渲染到 `/etc/nginx/templates/` 。通配游戏域 server 的 `server_name` 从硬编码 `*.games.example.com` 改为 `GAMES_SERVER_NAME` 变量，并新增 `location /api/` 同源反代到 `api:8080` ——此前 prod 子域运行时根本够不着 bundle-key（ `/api` ）。运行时三件套（`/__bootstrap` 、`/sw.js` 、`/agent.js` ）与 404 兜底骨架不变，形状由 `repo-yaml.test.ts` 对模板钉死。
```
- [ ] **步骤 1.7： **
``` bash
cd crearte
git status --short # 应只有 deploy/、src/scripts/、docs/CHANGELOG.md
git add -A && git commit -m "feat(deploy): template nginx conf, wildcard block gains same-origin /api proxy
- deploy/nginx.conf -> nginx.conf.template (GAMES_SERVER_NAME rendered by
nginx entrypoint envsubst; prod wildcard host was hardcoded dead config)
- wildcard game server adds location /api/ -> api:8080 so prod subdomain
play runtime can fetch bundle-key same-origin (dev-parity with vite)
- repo-yaml.test.ts guards the template shape incl. /api/ assertions
- docs: CHANGELOG 0.15.0"
```
---
### 任务 2：
- [ ] **步骤 2.1：合并（--no-ff，禁 fast-forward） **
``` bash
cd crearte
git checkout master && git pull --ff-only origin master
git merge --no-ff feat/prod-nginx-wildcard-api -m "Merge branch 'feat/prod-nginx-wildcard-api' — prod play runtime via templated nginx wildcard /api proxy (P1)"
```
预期：新增 merge commit，无冲突（master 自 f12cbf1 后无新提交；若 pull 带来新改动导致冲突，停下向用户报告，勿强合）。
- [ ] **步骤 2.2：推送 + 删分支 **
``` bash
git push origin master
git branch -d feat/prod-nginx-wildcard-api && git push origin --delete feat/prod-nginx-wildcard-api
git log --oneline -2 # 记录 merge hash，供 wrapper ROADMAP 状态引用
```
---
### 任务 3：
**分支： ** `cd crearte-deploy && git checkout -b feat/prod-write-side`
- [ ] **步骤 3.1： **
`docker-compose.yml` ：
``` yaml
# L5（
POSTGRES_PASSWORD : ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
# L54（ （
DATABASE_URL : postgres://crearte:${POST…rd}
# L58/L59（
MINIO_ROOT_USER : ${MINIO_ROOT_USER:-minioadmin}
MINIO_ROOT_PASSWORD : ${MINIO…min}
```
> api-dev L54 一并改：anchor 共享，dev/prod 同受 `:?` 约束——README 迁移警告覆盖（任务 4）。
- [ ] **步骤 3.2： **
`api-prod` 服务块整体替换为：
``` yaml
api-prod :
profiles : [ "prod" ]
build : *api-build
image : crearte-server:prod
restart : unless-stopped
depends_on :
db-prod :
condition : service_healthy
minio-prod :
condition : service_started
environment :
<< : *api-env
DATABASE_URL : postgres://crearte:${POST…rd}
STORAGE_S3_ENDPOINT : http://minio-prod:9000
STORAGE_S3_BUCKET : ${MINIO_BUCKET:-crearte}
STORAGE_S3_ACCESS_KEY_ID : ${MINIO_ROOT_USER:?set MINIO_ROOT_USER in .env}
STORAGE_S3_SECRET_ACCESS_KEY : ${MINI…?:set MINIO_ROOT_PASSWORD in .env}
STORAGE_S3_FORCE_PATH_STYLE : "true"
# 浏览器可达的公开基址（PublicURL = base + "/" + key，需含 bucket 段）
STORAGE_S3_PUBLIC_BASE_URL : http://localhost:${MINIO_PROD_PORT:-9001}/${MINIO_BUCKET:-crearte}
# CORS 通配放行：host == base 或 *.base；
GAMES_BASE_DOMAIN : localhost
CORS_ALLOWED_ORIGINS : ${HOST_ORIGIN:-http://localhost:8080}
networks :
default :
aliases : [ api]
healthcheck :
<< : *api-healthcheck
```
- [ ] **步骤 3.3：新增 minio-prod 服务 **
紧接 `api-prod` 之后（`db-debug` 之前）插入：
``` yaml
minio-prod :
profiles : [ "prod" ]
image : pgsty/minio:latest
restart : unless-stopped
command : [ "server" , "/data" ]
ports :
- "${MINIO_PROD_PORT:-9001}:9000"
environment :
MINIO_ROOT_USER : ${MINIO_ROOT_USER:?set MINIO_ROOT_USER in .env}
MINIO_ROOT_PASSWORD : ${MINI…?:set MINIO_ROOT_PASSWORD in .env}
# 游玩/封面跨源直连（与 minio-dev 同策略）
MINIO_API_CORS_ALLOW_ORIGIN : "*"
volumes :
- minio-data-prod:/data
```
- [ ] **步骤 3.4：web-prod 补构建参数与模板变量 **
`web-prod` 服务块整体替换为：
``` yaml
web-prod :
profiles : [ "prod" ]
build :
context : ../crearte
dockerfile : deploy/Dockerfile
args :
VITE_API_BASE_URL : /
VITE_GAMES_BASE_DOMAIN : ${PUBLIC_GAMES_HOST:-localhost:8080}
VITE_HOST_ORIGIN : ${HOST_ORIGIN:-http://localhost:8080}
image : crearte:prod
restart : unless-stopped
depends_on :
- api-prod
environment :
GAMES_SERVER_NAME : ${GAMES_SERVER_NAME:-*.localhost}
ports :
- "8080:80"
```
> `PUBLIC_GAMES_HOST`（客户端 host:port 拼接用）与 api 的 `GAMES_BASE_DOMAIN`（
- [ ] **步骤 3.5：卷声明追加 **
文件尾 `volumes:` 块追加一行（不动既有卷名）：
``` yaml
minio-data-prod :
```
- [ ] **步骤 3.6： **
``` bash
# 复制为 .env 后填写；.env 已被 .gitignore 忽略，绝不提交
# 生成 secret：
AUTH_TOKEN_SECRET =
BUNDLE_KEK_ACTIVE = k1
BUNDLE_KEK_k1 =
# Postgres 口令（0.5.0 起无默认值，缺失 compose 直接报错）。
# 老部署务必显式写旧卷的真实口令，否则鉴权失败，见 README「数据与配置」迁移警告。
POSTGRES_PASSWORD =
# MinIO root 凭据（:? 必填）。本机 dev/prod 演练可填 minioadmin/minioadmin；
# 任何对外可达的 prod 必须换强口令：openssl rand -base64 32
MINIO_ROOT_USER =
MINIO_ROOT_PASSWORD =
# prod 写侧可选项（默认值即本机自包含演练形态，详见 README prod 小节）：
# MINIO_PROD_PORT=9001 # prod MinIO 主机端口（dev 用 9000）
# HOST_ORIGIN=http://localhost:8080 # 主站对外 origin（ ）
# PUBLIC_GAMES_HOST=localhost:8080 # 游玩子域基址 host:port（客户端拼 <sub>:port）
# GAMES_SERVER_NAME=*.localhost # nginx 通配 server_name（真域名时 *.games.example.com）
# MINIO_BUCKET=crearte
# macOS / 网络盘上热更新不触发时设为 true
# CHOKIDAR_USEPOLLING=false
```
---
### 任务 4：
- [ ] **步骤 4.1： **
``` markdown
### prod 栈写侧（本机自包含演练）
prod 与 dev 互斥（都占 8080）。`minio-prod` （主机端口默认 **9001 ** ）为 prod 启用写侧路由（上传/投稿/审核/预览）；virtual 作品站内游玩走 `http://<sub>.localhost:8080` ——web-prod 的 nginx 通配块按 `GAMES_SERVER_NAME` 渲染三件套 + `/api/` 同源反代，与 dev 的 vite 行为对齐。
```bash
cp .env.example .env # 必填 5 项：AUTH_TOKEN_SECRET、BUNDLE_KEK_k1、POSTGRES_PASSWORD、MINIO_ROOT_USER、MINIO_ROOT_PASSWORD
docker compose --profile prod up -d --build
# prod 卷首次创建后一次性初始化桶（单引号刻意——防宿主 shell 展开，容器内凭 compose 注入的凭据完成）：
docker compose --profile prod exec minio-prod sh -c 'mc alias set local http://localhost:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" && mc mb --ignore-existing local/crearte && mc anonymous set download local/crearte'
```
迁真实服务器的最小清单（本轮演练未含 TLS）：泛解析 `*.games.<域名>` → 主机；`.env` 设 `HOST_ORIGIN` /`PUBLIC_GAMES_HOST` /`GAMES_SERVER_NAME` 为真实值并同步 api 的 `GAMES_BASE_DOMAIN` ； `MINIO_PROD_PORT` 收内网或换外部 S3（改 `STORAGE_S3_*` 五项即可，应用零改动）；上反代 TLS（Caddy/certbot + 通配证书）后把 `STORAGE_S3_PUBLIC_BASE_URL` 、`HOST_ORIGIN` 切 https——server CORS 对 https 子域直接放行。
```
- [ ] **步骤 4.2：
卷列表行改为提及 `minio-data-prod`；并在其下追加迁移警告：
```markdown
- **0.5.0 口令迁移警告**：
```
- [ ] **步骤 4.3： **
`docs/CHANGELOG.md` 顶部（`## [0.4.0]` 之前）插入：
``` markdown
## [0.5.0] - 2026-09-29
### Added / 新增
- The prod profile gains a full write side: new `minio-prod` object storage (host port `${MINIO_PROD_PORT:-9001}` , volume `minio-data-prod` , CORS-open) wired to `api-prod` via `STORAGE_S3_*` , plus `GAMES_BASE_DOMAIN=localhost` and `CORS_ALLOWED_ORIGINS` — upload/submission/review/preview routes now register in prod instead of 404-ing. `web-prod` gained `GAMES_SERVER_NAME` (renders the templated nginx wildcard block) and `VITE_GAMES_BASE_DOMAIN` /`VITE_HOST_ORIGIN` build args for the `*.localhost` play runtime. One-time prod bucket init and the real-server TLS checklist are in README.
- prod profile 补齐写侧全链路：新增 `minio-prod` （主机端口 `${MINIO_PROD_PORT:-9001}` 、卷 `minio-data-prod` 、开放 CORS），`api-prod` 配置 `STORAGE_S3_*` 与 `GAMES_BASE_DOMAIN=localhost` 、`CORS_ALLOWED_ORIGINS` ——上传/投稿/审核/预览路由在生产启用（此前一律 404）。`web-prod` 新增 `GAMES_SERVER_NAME` （渲染 nginx 模板通配块）与游玩运行时构建参数 `VITE_GAMES_BASE_DOMAIN` /`VITE_HOST_ORIGIN` 。prod 桶一次性初始化与真服务器 TLS 清单见 README。
### Changed / 变更
- `POSTGRES_PASSWORD` lost its `crearte` fallback: the env anchor and both `DATABASE_URL` s use `${POSTGRES_PASSWORD:?…}` , so compose fails fast when missing. Old checkouts must set the line explicitly to match the volume's frozen password (see README migration warning). `MINIO_ROOT_USER` /`MINIO_ROOT_PASSWORD` became `:?` -required (empty placeholders in `.env.example` ; minioadmin stays fine for local drills) and `minio-dev` now spells its defaults via the same variables.
- `POSTGRES_PASSWORD` 去掉 `crearte` 兜底：anchor 与两条 `DATABASE_URL` 改为 `${POSTGRES_PASSWORD:?…}` ，缺失即快速失败；既有部署须显式补写旧卷口令（见 README 迁移警告）。`MINIO_ROOT_USER` /`MINIO_ROOT_PASSWORD` 升为 `:?` 必填（`.env.example` 空占位；本机演练填 minioadmin 即可），`minio-dev` 默认值经同组变量显式化（行为不变）。
```
---
### 任务 5：
**前置： ** 任务 2 已完成（prod 镜像构建需要 master 上的模板 nginx）。以下命令全部在 `crearte-deploy/` 执行。
- [ ] **步骤 5.1：生成 .env **
``` bash
test -f .env && echo "ABORT: .env 已存在，停下核对而不是覆盖" || cp .env.example .env
{
echo " AUTH_TOKEN_SECRET= $( openssl rand -base64 32) "
echo " BUNDLE_KEK_k1= $( openssl rand -base64 32) "
echo "POSTGRES_PASSWORD=crearte"
echo "MINIO_ROOT_USER=minioadmin"
echo "MINIO_ROOT_PASSWORD=***"
} >> .env
sed -i '/^AUTH_TOKEN_SECRET=$/D;/^BUNDLE_KEK_k1=$/D;/^POSTGRES_PASSWORD=$/D;/^MINIO_ROOT_USER=$/D;/^MINIO_ROOT_PASSWORD=$/D' .env
```
- [ ] **步骤 5.2：四 profile config 全静默 **
``` bash
for p in dev prod debug mock; do docker compose --profile $p config -q || echo " FAIL $p " ; done
```
预期：无输出无 FAIL。再验守卫确实生效：`POSTGRES_PASSWORD= docker compose --profile prod config -q` 应报 required variable 错误（测后恢复）。
- [ ] **步骤 5.3： **
``` bash
docker compose --profile prod up -d --build
docker compose --profile prod ps
```
预期：`api-prod healthy` 、`db-prod healthy` 、`web-prod` /`minio-prod` running。首拉镜像慢属正常（GOPROXY 已指 goproxy.cn）。
- [ ] **步骤 5.4： ** （ `mc mb` /`anonymous set` 成功）
- [ ] **步骤 5.5：冒烟链（写侧 + 游玩链路 curl 等价物） **
逐条执行（`ADMIN_TOKEN` 全程 shell 变量传递，**不回显、不落盘敏感响应正文**）：
``` bash
set -euo pipefail
B = http://localhost:8080
# 1) healthz（经 web-prod 反代）
curl -sf $B /api/games >/dev/null && echo "catalog ok"
docker compose exec -T api-prod wget -qO- http://127.0.0.1:8080/healthz | grep -q ok && echo "healthz ok"
# 2) 注册 -> 提权 -> 重登（set-role 会失效旧 token，必须重登）
curl -s -o /tmp/p1reg.json -w '%{http_code}\n' -X POST $B /api/auth/register -H 'Content-Type: application/json' \
-d '{"email":"p1@example.com","password":"***","display_name":"P1 Smoke","username":"p1admin"}' # 201
docker compose exec -T api-prod /app/crearte-server user set-role p1@example.com admin
curl -s -o /tmp/p1login.json -w '%{http_code}\n' -X POST $B /api/auth/login -H 'Content-Type: application/json' \
-d '{"email":"p1@example.com","password":"***"}' # 200
ADMIN_TOKEN = *** -c "import json;print(json.load(open('/tmp/p1login.json'))['token'])" )
# 3) 上传真实 zip bundle
python3 -c "import zipfile;zipfile.ZipFile('/tmp/p1.zip','w').writestr('index.html','<h1>p1</h1>')"
curl -s -o /tmp/p1up.json -w '%{http_code}\n' -X POST $B /api/uploads -H " Authorization: Bearer $ADMIN_TOKEN " \
-F kind = bundle -F slug = p1-smoke -F version = v1 -F file = @/tmp/p1.zip # 201
UP_ID = $( python3 -c "import json;print(json.load(open('/tmp/p1up.json'))['upload_id'])" )
# 4) 投稿（virtual，
curl -s -o /tmp/p1sub.json -w '%{http_code}\n' -X POST $B /api/submissions -H " Authorization: Bearer $ADMIN_TOKEN " -H 'Content-Type: application/json' -d '{
"kind":"new_work","work_id":"p1admin/p1-smoke","bundle_upload_id":"' " $UP_ID " '","submit":true,
"payload":{"id":"p1admin/p1-smoke","runtime":"virtual","name":"P1 Smoke","url":"https://example.com",
"author":{"name":"P1"},"description":"prod write-side smoke","durationMinutes":{"min":1,"max":60},
"type":"puzzle","tags":["smoke"],"version":"v1"}}' # 201
SUB_ID = $( python3 -c "import json;print(json.load(open('/tmp/p1sub.json'))['id'])" )
curl -s -o /tmp/p1ext.json -w '%{http_code}\n' -X POST $B /api/submissions -H " Authorization: Bearer $ADMIN_TOKEN " -H 'Content-Type: application/json' -d '{
"kind":"new_work","work_id":"p1admin/p1-ext","submit":true,
"payload":{"id":"p1admin/p1-ext","runtime":"external","name":"P1 Ext","url":"https://example.com",
"author":{"name":"P1"},"description":"external smoke","durationMinutes":{"min":1,"max":60},
"type":"puzzle","tags":[]}}' # 201
# 5) 审核上架两作品
curl -s -o /dev/null -w 'approve1 %{http_code}\n' -X POST $B /api/admin/submissions/$SUB_ID /approve \
-H " Authorization: Bearer $ADMIN_TOKEN " -H 'Content-Type: application/json' -d '{"note":"smoke"}' # 200
EXT_SUB_ID = $( python3 -c "import json;print(json.load(open('/tmp/p1ext.json'))['id'])" )
curl -s -o /dev/null -w 'approve2 %{http_code}\n' -X POST $B /api/admin/submissions/$EXT_SUB_ID /approve \
-H " Authorization: Bearer $ADMIN_TOKEN " -H 'Content-Type: application/json' -d '{"note":"smoke"}' # 200
# 6) 详情：schema v2、playSubdomain、匿名可读
curl -s -o /tmp/p1det.json -w '%{http_code}\n' $B /api/games/p1admin/p1-smoke # 200（无 token）
python3 - <<'PY'
import json
d = json.load(open('/tmp/p1det.json'))
assert d['runtime'] == 'virtual' and d['playSubdomain'], d
assert d.get('bundle', {}).get('url'), '缺 bundle.url'
print('detail ok sub=', d['playSubdomain'])
PY
# 7) 通配子域：三件套 + /api 同源反代 + bundle-key（ ）
SUB = $( python3 -c "import json;print(json.load(open('/tmp/p1det.json'))['playSubdomain'])" )
for path in /__bootstrap /sw.js /agent.js; do
curl -sf --resolve " $SUB .localhost:8080:127.0.0.1 " " http:// $SUB .localhost:8080 $path " >/dev/null && echo " sub $path ok "
done
curl -s -o /tmp/p1key.json -w 'bundle-key %{http_code}\n' \
--resolve " $SUB .localhost:8080:127.0.0.1 " -H " Authorization: Bearer $ADMIN_TOKEN " \
" http:// $SUB .localhost:8080/api/games/p1admin/p1-smoke/bundle-key " # 200
python3 -c "import json;d=json.load(open('/tmp/p1key.json'));assert d['v']==1;print('key shape ok')"
shred -u /tmp/p1key.json 2>/dev/null || rm -f /tmp/p1key.json # 密钥材料不落盘残留
# 8) 跨源直连：bundle 密文匿名下载 + Origin=CORS 头（server 放行 *.localhost）
BU = $( python3 -c "import json;print(json.load(open('/tmp/p1det.json'))['bundle']['url'])" )
curl -sf -o /tmp/p1bundle.bin " $BU " && echo " bundle object ok ( $( stat -c%s /tmp/p1bundle.bin) B) "
curl -s -D- -o /dev/null -H " Origin: http:// $SUB .localhost:8080 " $B /api/games/p1admin/p1-smoke/bundle-key \
-H " Authorization: Bearer $ADMIN_TOKEN " | grep -i 'access-control-allow-origin' | grep -q " $SUB .localhost " && echo "cors wildcard ok"
curl -s -o /dev/null -w 'ext detail %{http_code}\n' $B /api/games/p1admin/p1-ext # 200
```
预期全绿。任一步 4xx/5xx：按 spec §4 排查（路由未注册→查 `STORAGE_S3_*` 是否被 `LoadStorage` 判不全；子域 404→查 `GAMES_SERVER_NAME` 渲染 `docker compose exec web-prod cat /etc/nginx/conf.d/default.conf` ）。
- [ ] **步骤 5.6： **
``` bash
docker compose --profile prod down
docker compose --profile dev up -d --build
docker compose --profile dev exec -T api-dev wget -qO- http://127.0.0.1:8080/healthz | grep -q ok && echo dev-api ok
docker compose --profile dev exec minio-dev sh -c "mc alias set local http://localhost:9000 minioadmin minioadmin && mc mb --ignore-existing local/crearte && mc anonymous set download local/crearte"
curl -sf http://localhost:8080/api/games >/dev/null && echo dev-catalog ok
docker compose --profile dev down # 无 -v
```
预期全绿（dev 的 minio-dev 仍走默认凭据；`.env` 里的 minioadmin 值与 `:-` 兼容）。
- [ ] **步骤 5.7：浏览器人工验收（可延后，标记即可） **
有 GUI 的机器上打开 `http://localhost:8080` （prod 栈），走 UI 上传→投稿→后台审核→站内游玩。本机为 headless，计划以步骤 5.5 的 curl 等价链为验收线，浏览器项标 `manual-deferred` 。
---
### 任务 6：
- [ ] **步骤 6.1 **
``` bash
cd crearte-deploy
git status --short # 应只有 docker-compose.yml、.env.example、README.md、docs/CHANGELOG.md；
git add -A && git commit -m "feat(prod): write side via minio-prod + games runtime env; drop POSTGRES_PASSWORD default
- minio-prod (host 9001, volume minio-data-prod) wired to api-prod
STORAGE_S3_*/GAMES_BASE_DOMAIN/CORS_ALLOWED_ORIGINS -> upload/submission/
review routes register in prod
- web-prod: GAMES_SERVER_NAME template var + VITE_GAMES_BASE_DOMAIN /
VITE_HOST_ORIGIN build args
- POSTGRES_PASSWORD & MINIO_ROOT_* become :?-required; .env.example synced;
README gains prod bucket init, password migration warning, TLS checklist
- docs: CHANGELOG 0.5.0"
git checkout master && git pull --ff-only origin master
git merge --no-ff feat/prod-write-side -m "Merge branch 'feat/prod-write-side' — prod write-side self-contained drill (P1)"
git push origin master
git branch -d feat/prod-write-side && git push origin --delete feat/prod-write-side
git log --oneline -2 # 记录 merge hash
```
---
### 任务 7：wrapper 收尾（状态、账目、计划登记）
- [ ] **步骤 7.1： **
P1 行状态列改为：`**完成**（ <任务2 merge hash>` / deploy ` <任务6 merge hash>`， 。文档索引表 P1 行实现计划列改为 ``docs/plans/2026-09-29-prod-write-side.md` （已执行，2026-09-29） `。
- [ ] **步骤 7.2：
` ``markdown
## [0.2.2] - 2026-09-29
### Docs / 文档
- Roadmap P1 delivered: prod write side went live in the compose drill — minio-prod + api-prod storage/games env + templated nginx wildcard block (crearte ` <>` / crearte-deploy ` <>`), POSTGRES_PASSWORD default retired, TLS deferred by design with a real-server checklist in README.
- 路线图 P1 交付：prod 写侧在本机演练栈完整启用——minio-prod、api-prod 存储/游玩域名环境、nginx 通配块模板化（crearte ` <>` / crearte-deploy ` <>`）；POSTGRES_PASSWORD 默认值退役；TLS 按设计缓做，真机清单已入 README。
` ``
（ ` 处以真实 merge hash 替换；英文行紧接中文行。）
- [ ] **步骤 7.3： （ ）
` ``bash
cd ..
git add docs/ROADMAP.md docs/CHANGELOG.md docs/plans/ docs/specs/
git commit -m "docs: P1 delivered — prod write-side drill merged; plan registered, changelog 0.2.2"
git push origin master
` ``
- [ ] **步骤 7.4：终态核验**
` ``bash
git -C crearte pull --ff-only origin master && git -C crearte log --oneline -1
git -C crearte-deploy pull --ff-only origin master && git -C crearte-deploy log --oneline -1
./clone_all.sh # 应输出 3 updated
` ``
---
## 自检（写完后执行，已内联修复）
1. **规格覆盖度**：
2. **占位符扫描**： <>` 为运行时事实（任务 2/6 执行时产生），其余无 TODO/待定。✔
3. **类型/命名一致性**： GAMES_SERVER_NAME`（ PUBLIC_GAMES_HOST`/` HOST_ORIGIN`/` MINIO_PROD_PORT`/` MINIO_BUCKET`（ deploy/nginx.conf.template`（
**范围外提醒（不入本计划）**：HANDOFF §4 前端零散 backlog 与本计划无关；若冒烟 5.5 步骤 7 发现 ` sw.js`/` agent.js` 在 prod dist 缺失（` nginx exec ls /usr/share/nginx/html`），那是 crearte 构建产物的独立缺陷，上报而非顺手修。
XingfenD