Files

T

XingfenD 6b3a4e5240 docs(plan): docker deploy conformance implementation plan (5 tasks); spec: smoke storage path item

2026-09-07 19:42:39 +08:00

27 KiB

Raw Blame History

Docker 部署规范化改写实施计划

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: 把 booklib 的 Docker 部署重写为团队规范形态：dev/release 双 compose、共享 named volumes、prepare.sh 渲染配置、dev 源码热挂载 + delve、release 编译产物、文件存储挂 deploy/api/storage。

Architecture: 单 API(backend/cmd/server) + SPA(web)不变；部署层重写为 deploy/ 内自包含（compose 项目目录=deploy/，build context=仓库根 ..）。配置由 deploy/templates/*.tpl 经 prepare.sh 渲染为 deploy/nginx/、deploy/redis/ 产物后 :ro 挂载。

Tech Stack: Docker Compose v2、Go 1.26（delve headless）、Node 22（vite）、nginx:1.27-alpine、postgres:16-alpine、redis:7-alpine。

Spec: docs/superpowers/specs/2026-09-07-docker-deploy-spec-design.md（本计划的验收即 spec §9）

Global Constraints

compose 项目名固定 name: booklib（两个 compose 文件顶层都有）；named volume 一律命名 postgres_data、redis_data（实际名 booklib_postgres_data/booklib_redis_data），两文件完全一致。
dev = deploy/docker-compose.dev.yml（target: dev 镜像、源码挂载、PG 宿主 5432、Redis 宿主 6379、delve 2345、healthcheck 门控）；release = deploy/docker-compose.yml（Dockerfile.*.prod target: runner、无源码挂载、infra 不出宿主端口）。
所有 :ro 挂载的配置文件都是 prepare.sh 渲染产物，模板是唯一编辑入口；渲染产物目录全部 gitignore。
文件存储路径统一 deploy/api/storage → 容器 /data/books，CACHE_DIR=/data/books/cache。
环境变量键名不变：JWT_SECRET、ADMIN_USER、ADMIN_PASSWORD、SCAN_INTERVAL_SEC（.env 迁至 deploy/.env）。
删除清单（最终态不再存在）：根 docker-compose.yml、根 .env.example、deploy/Dockerfile.api、deploy/Dockerfile.web、deploy/nginx.conf、根 library/ 约定。
不动业务代码，唯一两处适配：web/vite.config.ts 代理目标读 env、两个 smoke 脚本的 .env 路径。

Task 1: prepare.sh + 配置模板 + .env 迁移

Files:

Create: deploy/templates/nginx.conf.tpl、deploy/templates/default.conf.tpl、deploy/templates/redis.conf.tpl
Create: deploy/prepare.sh（chmod +x）
Create: deploy/api/storage/.gitkeep
Move: .env.example → deploy/.env.example；本地 .env → deploy/.env（untracked，用 mv）
Modify: .gitignore、.dockerignore、scripts/smoke.sh:6、scripts/smoke-web.sh:6

Interfaces:

Produces: 渲染产物 deploy/nginx/nginx.conf、deploy/nginx/conf.d/default.conf、deploy/redis/redis.conf；目录 deploy/logs/nginx/。变量表：WEB_PORT(8080)、NGINX_CLIENT_MAX_BODY_SIZE(200m)、REDIS_MAXMEMORY(128mb)、REDIS_MAXMEMORY_POLICY(allkeys-lru)、DELVE_PORT(2345)。
Step 1: 写三个模板

deploy/templates/nginx.conf.tpl（nginx 主配置，日志写挂载目录）：

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    access_log  /var/log/nginx/access.log;

    sendfile        on;
    keepalive_timeout  65;

    gzip  on;
    gzip_types text/css application/javascript application/json image/svg+xml;

    include /etc/nginx/conf.d/*.conf;
}

deploy/templates/default.conf.tpl（server 块，内容 = 现 deploy/nginx.conf，仅 max_body 参数化；此文件后续会被 entrypoint 拷入容器再注入 resolver，所以 resolver 行保留占位值）：

server {
  listen 80;
  client_max_body_size {{NGINX_CLIENT_MAX_BODY_SIZE}};
  # 地址为占位默认值(127.0.0.11=Docker 内嵌 DNS);容器 entrypoint 启动时会按
  # /etc/resolv.conf 的首个 nameserver 重写本行,兼容 podman aardvark-dns。
  resolver 127.0.0.11 valid=10s;

  # spec §7 风险接受所假设的 CSP:全部同源,blob:/data: 供 SW/reader 用
  add_header Content-Security-Policy "default-src 'self'; img-src 'self' blob: data:; worker-src 'self' blob:; style-src 'self' 'unsafe-inline'; connect-src 'self' blob: data:; object-src 'none'; frame-src 'self' blob:" always;

  location /api/ {
    set $api_upstream http://api:8080;   # 变量式 → 每次按 DNS 解析,scale 后轮询到新副本(spec §11)
    proxy_pass $api_upstream;            # 无 URI 部分:保留 /api 前缀转发
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  location / {
    root /usr/share/nginx/html;
    try_files $uri /index.html;
  }
}

deploy/templates/redis.conf.tpl：

# booklib redis 配置 — 由 deploy/prepare.sh 从 templates/redis.conf.tpl 渲染,勿直接编辑产物
maxmemory {{REDIS_MAXMEMORY}}
maxmemory-policy {{REDIS_MAXMEMORY_POLICY}}
dir /data

Step 2: 写 deploy/prepare.sh 并 chmod +x

#!/usr/bin/env bash
# 渲染 deploy/templates/*.tpl → deploy/nginx、deploy/redis,并创建运行所需目录。
# 约定:每次 up 之前(或改模板/.env 后)必须重跑本脚本。幂等,可反复执行。
set -eu
cd "$(dirname "$0")"

if [ -f .env ]; then
  set -a; . ./.env; set +a
fi

NGINX_CLIENT_MAX_BODY_SIZE=${NGINX_CLIENT_MAX_BODY_SIZE:-200m}
REDIS_MAXMEMORY=${REDIS_MAXMEMORY:-128mb}
REDIS_MAXMEMORY_POLICY=${REDIS_MAXMEMORY_POLICY:-allkeys-lru}

for t in templates/nginx.conf.tpl templates/default.conf.tpl templates/redis.conf.tpl; do
  [ -f "$t" ] || { echo "prepare.sh: missing template $t" >&2; exit 1; }
done

mkdir -p nginx/conf.d redis logs/nginx api/storage

sed -e "s|{{NGINX_CLIENT_MAX_BODY_SIZE}}|${NGINX_CLIENT_MAX_BODY_SIZE}|g" \
  templates/nginx.conf.tpl > nginx/nginx.conf
sed -e "s|{{NGINX_CLIENT_MAX_BODY_SIZE}}|${NGINX_CLIENT_MAX_BODY_SIZE}|g" \
  templates/default.conf.tpl > nginx/conf.d/default.conf
sed -e "s|{{REDIS_MAXMEMORY}}|${REDIS_MAXMEMORY}|g" \
  -e "s|{{REDIS_MAXMEMORY_POLICY}}|${REDIS_MAXMEMORY_POLICY}|g" \
  templates/redis.conf.tpl > redis/redis.conf

echo "prepare.sh: rendered nginx($(pwd)/nginx), redis($(pwd)/redis), logs($(pwd)/logs/nginx), storage($(pwd)/api/storage)"

Step 3: 迁移 .env 与 .env.example

git mv .env.example deploy/.env.example
[ -f .env ] && mv .env deploy/.env

改写 deploy/.env.example 为：

JWT_SECRET=change-me-openssl-rand-hex-32
ADMIN_USER=admin
ADMIN_PASSWORD=change-me-min-8
SCAN_INTERVAL_SEC=60

# ---- 部署参数(deploy/prepare.sh 渲染模板 / compose 插值用) ----
WEB_PORT=8080
NGINX_CLIENT_MAX_BODY_SIZE=200m
REDIS_MAXMEMORY=128mb
REDIS_MAXMEMORY_POLICY=allkeys-lru
DELVE_PORT=2345

Step 4: 更新 .gitignore / .dockerignore / smoke 脚本，并放置 storage 占位

mkdir -p deploy/api/storage && touch deploy/api/storage/.gitkeep

.gitignore：删除 library/ 行，追加：

deploy/nginx/
deploy/redis/redis.conf
deploy/logs/
deploy/api/storage/*
!deploy/api/storage/.gitkeep

.dockerignore：删除 library/ 行，追加 deploy/logs/、deploy/nginx/、deploy/redis/、deploy/api/storage/。

scripts/smoke.sh 和 scripts/smoke-web.sh 的第 6 行 [ -f .env ] && set -a && . ./.env && set +a 均替换为：

ENV_FILE=${ENV_FILE:-deploy/.env}
[ -f "$ENV_FILE" ] || ENV_FILE=.env
[ -f "$ENV_FILE" ] && set -a && . "./$ENV_FILE" && set +a

scripts/smoke.sh 依赖旧的 ./library:/data/books 绑定（第 28、55 行），随存储路径迁移同步改为：

mkdir -p deploy/api/storage/smoke-books        # 原:mkdir -p library/smoke-books
[ ! -f deploy/api/storage/smoke-books/note.txt ] || die "file survived delete"   # 原:library/smoke-books/note.txt

Step 5: 验证渲染

deploy/prepare.sh && deploy/prepare.sh   # 幂等跑两遍
grep -R '{{' deploy/nginx deploy/redis && echo "FAIL: placeholder left" || echo OK
grep -q 'maxmemory 128mb' deploy/redis/redis.conf && echo OK
ls deploy/logs/nginx deploy/api/storage

Expected: 两次 OK，无 FAIL。再验证缺省值路径：临时 env -i 不行（脚本 source .env），改用 ENV_FILE 无法关——直接确认 deploy/.env 不存在时仍渲染默认值：mv deploy/.env /tmp/e 2>/dev/null; deploy/prepare.sh; grep 'maxmemory 128mb' deploy/redis/redis.conf && mv /tmp/e deploy/.env 2>/dev/null; true

Step 6: Commit

git add -A
git commit -m "feat(deploy): prepare.sh + config templates, migrate env to deploy/, gitignore rendered outputs"

Task 2: 双 Dockerfile（dev/prod）+ entrypoint-resolver 改造

Files:

Create: deploy/Dockerfile.api.dev、deploy/Dockerfile.api.prod、deploy/Dockerfile.web.dev、deploy/Dockerfile.web.prod
Modify: deploy/entrypoint-resolver.sh
Delete: deploy/Dockerfile.api、deploy/Dockerfile.web、deploy/nginx.conf

Interfaces:

Consumes: Task 1 的 /etc/booklib/{nginx.conf,default.conf} 挂载约定（Task 3 落地）。
Produces: 可构建镜像 target：Dockerfile.api.dev→dev、Dockerfile.api.prod→runner、Dockerfile.web.dev→dev、Dockerfile.web.prod→runner；build context=仓库根。
Step 1: 写 deploy/Dockerfile.api.dev

FROM golang:1.26 AS base
WORKDIR /app

FROM base AS dev
# 源码由 compose 挂载进 /app;镜像只带工具链 + delve
RUN go install github.com/go-delve/delve/cmd/dlv@latest
EXPOSE 8080 2345
CMD ["sh", "-c", "go mod download && dlv debug ./cmd/server --headless --listen=0.0.0.0:2345 --api-version=2 --continue --log"]

Step 2: 写 deploy/Dockerfile.api.prod

FROM golang:1.26-alpine AS build
WORKDIR /src
COPY backend/go.mod backend/go.sum ./
RUN go mod download
COPY backend/ ./
RUN CGO_ENABLED=0 go build -trimpath -o /server ./cmd/server

FROM alpine:3.20 AS runner
RUN adduser -D -H app
COPY --from=build /server /server
# /data/books 由宿主 bind(./api/storage)覆盖;/data 下目录预建并授权,兼容 podman
RUN mkdir -p /data && chown app:app /data
USER app
EXPOSE 8080
ENTRYPOINT ["/server"]

Step 3: 写 deploy/Dockerfile.web.dev

FROM node:22 AS dev
WORKDIR /app
COPY web/package.json web/package-lock.json ./
RUN npm ci
EXPOSE 5173
CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]

Step 4: 写 deploy/Dockerfile.web.prod（不再 baked nginx 配置）

FROM node:22-alpine AS build
WORKDIR /src
COPY web/package.json web/package-lock.json ./
RUN npm ci
COPY web/ ./
RUN npm run build

FROM nginx:1.27-alpine AS runner
COPY --chmod=755 deploy/entrypoint-resolver.sh /entrypoint-resolver.sh
COPY --from=build /src/dist /usr/share/nginx/html
# nginx 配置不 bake 进镜像:由 compose 挂到 /etc/booklib/(渲染产物),
# entrypoint 启动时拷入原位、注入运行时 resolver 再 exec nginx
ENTRYPOINT ["/entrypoint-resolver.sh"]

Step 5: 改 deploy/entrypoint-resolver.sh（先拷贝再 sed，因 :ro 挂载不可原地改写）

#!/bin/sh
# 双运行时(Docker/podman)DNS 修复:镜像内 baked 的 resolver 地址无法同时成立
# (Docker=127.0.0.11,podman aardvark=网络网关,见容器 /etc/resolv.conf)。
# 启动前取 resolv.conf 首个 nameserver 注入 nginx 配置,保住 spec §11 的
# 变量式 proxy_pass 运行时重解析(valid=10s,scale/重建后秒级感知新 IP)。
# 配置以 :ro 挂在 /etc/booklib/(deploy/prepare.sh 渲染产物),先拷入原位再改写。
set -eu
for f in nginx.conf default.conf; do
  [ -r "/etc/booklib/$f" ] || { echo "entrypoint-resolver: missing /etc/booklib/$f — 先跑 deploy/prepare.sh" >&2; exit 1; }
done
cp /etc/booklib/nginx.conf /etc/nginx/nginx.conf
cp /etc/booklib/default.conf /etc/nginx/conf.d/default.conf
RESOLVER=$(awk '/^nameserver/{print $2; exit}' /etc/resolv.conf 2>/dev/null || true)
[ -n "$RESOLVER" ] || RESOLVER=127.0.0.11
CONF=/etc/nginx/conf.d/default.conf
sed -i "s#resolver [0-9a-fA-F:.]* valid=#resolver ${RESOLVER} valid=#" "$CONF"
echo "entrypoint-resolver: resolver=${RESOLVER} injected into ${CONF}"
nginx -t
if [ $# -gt 0 ]; then exec "$@"; fi
exec nginx -g 'daemon off;'

Step 6: 删除旧文件并构建四个镜像验证

git rm deploy/Dockerfile.api deploy/Dockerfile.web deploy/nginx.conf
docker build -f deploy/Dockerfile.api.dev  --target dev    -t booklib:api-dev .
docker build -f deploy/Dockerfile.api.prod --target runner -t booklib:api-prod .
docker build -f deploy/Dockerfile.web.dev  --target dev    -t booklib:web-dev .
docker build -f deploy/Dockerfile.web.prod --target runner -t booklib:web-prod .
docker run --rm --entrypoint sh booklib:api-prod -c 'test -x /server && echo binary-ok'
docker run --rm --entrypoint sh booklib:api-dev -c 'command -v dlv >/dev/null && echo dlv-ok'
docker run --rm --entrypoint sh booklib:web-dev -c 'test -d node_modules/vite && echo deps-ok'

Expected: 四个 build 成功；binary-ok、dlv-ok、deps-ok。

Step 7: Commit

git add -A
git commit -m "feat(deploy): split Dockerfiles into dev/runner targets, entrypoint copies rendered nginx conf before resolver injection"

Task 3: release compose（deploy/docker-compose.yml）

Files:

Create: deploy/docker-compose.yml
Delete: docker-compose.yml（根）

Interfaces:

Consumes: Task 1 渲染产物路径、Task 2 的镜像 target 与 /etc/booklib/ 约定、deploy/.env。
Produces: 服务名 web|api|postgres|redis（Task 4 dev 文件沿用同名）。
Step 1: 写 deploy/docker-compose.yml

# release:编译产物、无源码挂载、infra 端口不出宿主机
name: booklib
services:
  web:
    build: { context: .., dockerfile: deploy/Dockerfile.web.prod, target: runner }
    ports: ["${WEB_PORT:-8080}:80"]
    volumes:
      - ./nginx/nginx.conf:/etc/booklib/nginx.conf:ro
      - ./nginx/conf.d/default.conf:/etc/booklib/default.conf:ro
      - ./logs/nginx:/var/log/nginx
    depends_on: [api]
  api:
    build: { context: .., dockerfile: deploy/Dockerfile.api.prod, target: runner }
    environment:
      DATABASE_URL: postgres://lib:lib@postgres:5432/lib?sslmode=disable
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      ADMIN_USER: ${ADMIN_USER}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      BOOKS_DIR: /data/books
      CACHE_DIR: /data/books/cache
      SCAN_INTERVAL_SEC: ${SCAN_INTERVAL_SEC:-60}
    volumes:
      - ./api/storage:/data/books
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_started }
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: lib, POSTGRES_PASSWORD: lib, POSTGRES_DB: lib }
    volumes: [postgres_data:/var/lib/postgresql/data]
    healthcheck: { test: ["CMD-SHELL", "pg_isready -U lib"], interval: 2s, timeout: 2s, retries: 30 }
  redis:
    image: redis:7-alpine
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]
    volumes:
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - redis_data:/data
volumes:
  postgres_data:
  redis_data:

Step 2: 删除根 compose

git rm docker-compose.yml

Step 3: 未跑 prepare 的失败路径验证（spec §8）

mv deploy/nginx /tmp/bk-ng && docker compose -f deploy/docker-compose.yml up -d 2>&1 | grep -i "not found\|error"; mv /tmp/bk-ng deploy/nginx

Expected: compose 因绑定挂载源缺失报错，无容器半起（如有残留先 docker compose -f deploy/docker-compose.yml down）。

Step 4: 起 release 并跑双冒烟

deploy/prepare.sh
docker compose -f deploy/docker-compose.yml up -d --build
bash scripts/smoke.sh && bash scripts/smoke-web.sh
docker compose -f deploy/docker-compose.yml ps   # 全 healthy/running
curl -s localhost:8080/api/healthz

Expected: 两套冒烟全绿、ok。若宿主 :8080 被 Task 4 前的旧栈占用，先 docker compose down 旧项目。

Step 5: 验证卷名与 nginx 日志落宿主

docker volume ls | grep booklib_
docker compose -f deploy/docker-compose.yml exec web sh -c 'ls /etc/nginx/conf.d/default.conf >/dev/null && grep -m1 resolver /etc/nginx/conf.d/default.conf'
ls deploy/logs/nginx/   # 有 access.log(冒烟请求后)

Expected: booklib_postgres_data、booklib_redis_data；resolver 行已是容器内实际 nameserver（非 127.0.0.11 亦可——Docker 下就是 127.0.0.11，podman 下为网关 IP）；access.log 非空。

Step 6: Commit（数据卷留在盘上给 Task 4 做共享验证）

git add -A
git commit -m "feat(deploy): release compose under deploy/ with shared named volumes and rendered config mounts; drop root compose"

Task 4: dev compose（四服务全容器化）+ vite 代理适配

Files:

Create: deploy/docker-compose.dev.yml（整体重写，替换旧内容）
Modify: web/vite.config.ts（server.proxy 一行）

Interfaces:

Consumes: Task 2 dev 镜像（go/dlv/npm 可用）、Task 1 deploy/api/storage、deploy/redis/redis.conf、Task 3 的卷（同名 → 数据共享）。
Produces: VITE_PROXY_TARGET env 约定；dev 端口头约定：宿主 PG localhost:5432(lib/lib/lib)、Redis localhost:6379、delve :2345、vite :5173。
Step 1: vite 代理目标可配置

web/vite.config.ts 中 server: { proxy: { "/api": "http://localhost:8080" } }, 替换为：

  server: { proxy: { "/api": process.env.VITE_PROXY_TARGET ?? "http://localhost:8080" } },

Step 2: 重写 deploy/docker-compose.dev.yml

# dev:源码热挂载 + target: dev 镜像 + delve :2345,infra 端口暴露宿主,healthcheck 门控
# 起停用 down(不是 rm),否则 web 的匿名 node_modules 卷会成孤儿
name: booklib
services:
  postgres:
    image: postgres:16-alpine
    environment: { POSTGRES_USER: lib, POSTGRES_PASSWORD: lib, POSTGRES_DB: lib }
    ports: ["5432:5432"]
    volumes: [postgres_data:/var/lib/postgresql/data]
    healthcheck: { test: ["CMD-SHELL", "pg_isready -U lib"], interval: 2s, timeout: 2s, retries: 30 }
  redis:
    image: redis:7-alpine
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]
    ports: ["6379:6379"]
    volumes:
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - redis_data:/data
  api:
    build: { context: .., dockerfile: deploy/Dockerfile.api.dev, target: dev }
    command: sh -c "go mod download && dlv debug ./cmd/server --headless --listen=0.0.0.0:2345 --api-version=2 --continue --log"
    environment:
      DATABASE_URL: postgres://lib:lib@postgres:5432/lib?sslmode=disable
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
      ADMIN_USER: ${ADMIN_USER}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      BOOKS_DIR: /data/books
      CACHE_DIR: /data/books/cache
      SCAN_INTERVAL_SEC: ${SCAN_INTERVAL_SEC:-60}
    volumes:
      - ../backend:/app
      - ./api/storage:/data/books
    ports: ["${DELVE_PORT:-2345}:2345"]
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_started }
  web:
    build: { context: .., dockerfile: deploy/Dockerfile.web.dev, target: dev }
    command: npm run dev -- --host 0.0.0.0
    environment: { VITE_PROXY_TARGET: http://api:8080 }
    volumes:
      - ../web:/app
      - /app/node_modules
    ports: ["5173:5173"]
    depends_on: [api]
volumes:
  postgres_data:
  redis_data:

Step 3: 起 dev 栈并验证四要点

docker compose -f deploy/docker-compose.yml down          # 先停 release,端口让给 dev
deploy/prepare.sh
docker compose -f deploy/docker-compose.dev.yml up -d --build
curl -sf localhost:5173/api/healthz                     # vite 代理 → 容器 api:200
curl -sf localhost:5173 | grep -qi '<div id="root">'    # vite 页面
nc -z localhost 2345 && echo delve-ok                   # delve 端口
nc -z localhost 5432 && nc -z localhost 6379 && echo infra-ok

Expected: delve-ok、infra-ok，两个 curl 成功。

Step 4: 验证热重启语义（改码不 rebuild）

touch backend/cmd/server/main.go
docker compose -f deploy/docker-compose.dev.yml restart api
sleep 8 && curl -sf localhost:5173/api/healthz && echo hot-reload-ok

Expected: hot-reload-ok（dlv 重新编译挂载的源码后健康检查恢复）。

Step 5: 验证数据与 release 共享（spec §9.3）

Task 3 冒烟写入的数据（卷同名共享）应透过 dev 可见——用与 scripts/smoke.sh 相同的登录形状（/api/auth/login，body {"username","password"}）经 5173 代理断言：

set -a; . deploy/.env; set +a
TOK=$(curl -fsS localhost:5173/api/auth/login -H 'content-type: application/json' \
  -d "{\"username\":\"$ADMIN_USER\",\"password\":\"$ADMIN_PASSWORD\"}" | sed -E 's/.*"token":"([^"]+)".*/\1/')
[ -n "$TOK" ] && echo login-ok
curl -fsS localhost:5173/api/libraries -H "authorization: Bearer $TOK" | grep -q '"smoke"' && echo shared-data-ok

Expected: login-ok、shared-data-ok（libraries 含 Task 3 冒烟创建的 smoke 库）。

Step 6: Commit

git add -A
git commit -m "feat(deploy): dev compose runs full stack with source mounts, delve, shared volumes; vite proxy target via env"

Task 5: README 重写 + 旧卷迁移文档 + 终验

Files:

Modify: README.md（整体重写，见 Step 1）

Interfaces:

Consumes: Task 1–4 全部产物。
Produces: 无（收尾）。
Step 1: 重写 README.md

# Book & Comic Library

个人书库/漫画库:Go+Gin 后端(扫描/上传入库、多用户 JWT、阅读进度、磁盘+Redis 缓存)+ Docker Compose 部署。设计见 `docs/superpowers/specs/2026-09-04-book-comic-library-design.md`;部署规范见 `docs/superpowers/specs/2026-09-07-docker-deploy-spec-design.md`。

## Deploymode

- release:`deploy/docker-compose.yml` — 多阶段 `Dockerfile.{api,web}.prod`(target runner)编译产物,不挂源码;infra 端口只在容器网络。
- dev:`deploy/docker-compose.dev.yml` — 四服务全容器化,源码挂 `../backend:/app`、`../web:/app`(web 带匿名 `node_modules` 卷),`target: dev` 镜像;api 跑 `go mod download && dlv debug ./cmd/server`(热重启不 rebuild,delve :2345);infra 暴露宿主 PG 5432 / Redis 6379;healthcheck 门控。

## Volume Mount

- 共享 named volumes:`booklib_postgres_data`、`booklib_redis_data`(两个 compose 同名,dev/release 看到同一份数据;仅 `down -v` 清除)。
- 配置/日志绑定挂载:`deploy/nginx/{nginx.conf,conf.d/default.conf}`、`deploy/redis/redis.conf`(`:ro`)与 `deploy/logs/nginx` —— 全部来自 `deploy/prepare.sh`,**容器里配置不对/缺失 = 忘了重跑它**。
- 文件存储:`deploy/api/storage` → 容器 `/data/books`(缓存写 `/data/books/cache`)。

## 跑起来(生产形态)

```bash
cp deploy/.env.example deploy/.env   # 填 JWT_SECRET、ADMIN_USER、ADMIN_PASSWORD(≥8 位,低于 8 位 seed 会跳过并 log)
deploy/prepare.sh
docker compose -f deploy/docker-compose.yml up -d --build
bash scripts/smoke.sh && bash scripts/smoke-web.sh
```

- web: `http://localhost:8080`(`WEB_PORT` 可改),API 走 nginx `/api/` 前缀反代到无状态 api 副本(`--scale api=N`)。
- 原始书放进 `deploy/api/storage/`(挂到 `/data/books`),scanner 周期入库(默认 60s)。
- nginx access/error 日志:`deploy/logs/nginx/`。

## 开发

```bash
deploy/prepare.sh
docker compose -f deploy/docker-compose.dev.yml up -d --build
```

- 前端: http://localhost:5173(vite,HMR 直接生效;`/api` 代理到容器内 api)。
- Go 改码后:`docker compose -f deploy/docker-compose.dev.yml restart api`(重编译挂载源码,无需 rebuild)。
- 断点调试:delve headless 在 `localhost:2345`(VSCode launch:`{"type":"go","request":"attach","mode":"remote","host":"localhost","port":2345}`;命中断点后用 dlv 命令继续)。
- 直连基础设施跑测试:PG `localhost:5432`(lib/lib/lib)、Redis `localhost:6379`:

```bash
cd backend
export DATABASE_URL='postgres://lib:lib@localhost:5432/lib?sslmode=disable'
export REDIS_URL='redis://localhost:6379'
go vet ./... && gofmt -l .
go test -p 1 -count=1 ./...
```

`-p 1` 是必须的:集成测试共用同一个 PG 库,各自 `DELETE FROM ...` 清表——并行跑会互相删数据导致随机失败。dev 栈起停用 `down`(不是 `rm`),否则匿名 node_modules 卷成孤儿。无 PG/Redis 时依赖它们的测试自动 skip;Redis 挂掉不影响功能(全链路降级为 miss/放行,见 spec §9)。

前端门槛:`cd web && npm run check`(tsc + vitest + vite build)。

## 旧卷迁移(一次性,升级自上一版部署)

```bash
# 老 PG 数据 → 新共享卷
docker run --rm -v book-comic-library_pgdata:/from -v booklib_postgres_data:/to alpine cp -a /from/. /to/
# 老 cache 卷是封面/解压派生数据,直接丢弃(自动重建)
docker volume rm book-comic-library_pgdata book-comic-library_cache
```

书库文件:原宿主 `./library/` 的内容移入 `deploy/api/storage/`。

## 可信代理与限流

- nginx 在 compose 网络内,api 的 `ClientIP` 只信 `TRUSTED_PROXY_CIDRS`(逗号分隔 CIDR,默认 `172.16.0.0/12`,即 compose 网段)。外部伪造 `X-Forwarded-For` 换不掉限流桶;换部署网络时改这个 env。
- 登录限流 5 次/分钟/IP **按尝试计数,成功登录也计**——爆破和正常高频登录同账。

## 改 schema 前必读

`db.Migrate` 只执行 `schema.sql` 的 `CREATE TABLE IF NOT EXISTS`——对已存在的库**加列/改列不会生效**。任何列变更之前,必须先引入 `schema_migrations` 版本表 + 有序迁移脚本,否则老部署会静默跑在旧结构上。

## PWA

不可变资源(封面/CBZ 页/原文件)SW cache-first,读过的内容离线可翻;登出会清 SW 缓存。

Step 2: release 终验（spec §9.1/9.5）

docker compose -f deploy/docker-compose.dev.yml down
docker compose -f deploy/docker-compose.yml up -d --build
bash scripts/smoke.sh && bash scripts/smoke-web.sh
cd backend && go vet ./... && gofmt -l . && go test -p 1 -count=1 ./...
cd ../web && npm run check

Expected: 冒烟全绿、后端测试全过、前端 check 过。

Step 3: 规范符合性核对表（spec §9.4，逐条人工打勾）

规范条目	核对命令/位置
dev/release 两文件路径	`deploy/docker-compose{.dev,}.yml`
dev 源码挂载 + 匿名 node_modules	dev compose `volumes`
`target: dev` / `*.prod target: runner`	compose `build.target`
infra 端口:dev 暴露(5432/6379)、release 内网	两文件 `ports`
delve 2345	dev compose `ports`
healthcheck 门控	dev/release `depends_on.condition`
`{$project}_postgres/redis_data` 同名共享	`docker volume ls` 一次
渲染配置 `:ro` + logs 挂载	两文件 `volumes`
存储挂 `deploy/{service}/storage`	`./api/storage:/data/books`

Step 4: Commit

git add README.md
git commit -m "docs(readme): rewrite run/dev/migrate instructions for dev/release deploy spec"

27 KiB Raw Blame History Unescape Escape

Docker 部署规范化改写 实施计划

Global Constraints

Task 1: prepare.sh + 配置模板 + .env 迁移

Task 2: 双 Dockerfile（dev/prod）+ entrypoint-resolver 改造

Task 3: release compose（deploy/docker-compose.yml）

Task 4: dev compose（四服务全容器化）+ vite 代理适配

Task 5: README 重写 + 旧卷迁移文档 + 终验

27 KiB

Raw Blame History

Docker 部署规范化改写实施计划