From a2fc215ef9c9523835598b2902bd6f08919489a4 Mon Sep 17 00:00:00 2001
From: kennethcheng <a1478925630@163.com>
Date: Sun, 13 Sep 2026 17:19:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=A1=A5=E5=85=A8=20Docker=20?=
 =?UTF-8?q?=E9=83=A8=E7=BD=B2=E7=AB=A0=E8=8A=82(=E6=8B=93=E6=89=91?=
 =?UTF-8?q?=E5=9B=BE=20/=20=E9=95=9C=E5=83=8F=E8=A6=81=E7=82=B9=20/=20?=
 =?UTF-8?q?=E6=8C=81=E4=B9=85=E5=8C=96=20/=20=E5=8F=8D=E4=BB=A3)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

上条 commit (846b1a7) 把 deploy/ 目录实际文件都铺好了,但 README 的
"🐳 部署"还停留在"待完成"占位,新成员(以及未来的自己)看到 README
会以为 Docker 还没做。这条 commit 把 README 与实际状态对齐。

新增 / 改动 README.md:
- 仓库结构树:deploy/ 从"(待) docker-compose + nginx"改成
  "Docker 部署文件",列出 4 个子文件
- 替换 "🐳 部署(待完成)" 占位为完整章节:
  * 快速部署:一条 docker compose up -d
  * 部署拓扑:ASCII 图展示 web 容器 (nginx) 反代 /api 到 api 容器
    (GORM + SQLite),数据卷持久化
  * 镜像要点:表格列出 api / web 两个镜像的 base image + 关键配置
    (CGO=0 / tini / 非 root / corepack pnpm / gzip + 30 天 immutable cache)
  * 数据持久化:DB_PATH 路径 / volume 名 / 备份命令(docker run --rm 模板)
  * 反代建议:不要直接 8080 暴露公网,前面挡 NPM / Traefik,符合
    plan §17 "容器内 API 默认只监听内网"
  * 健康检查:API + web 都用 wget,compose 用 condition: service_healthy
  * 开发模式:不想装 Go 也能跑,流程:pnpm build -> docker compose up
  * 链回 deploy/README.md
- 路线图:Phase 5 标 done,Phase 6/7/8 标 pending(对应 Import/Export /
  Auth / 扩展)

未做(留待后续):
- README 截图(Docker 跑起来后再补)
- Traefik / NPM 自动 HTTPS 的具体配置(留给 plan §17 后续)
- 数据备份 cron / 灾备演练

风格保持与之前一致:中文为主,技术名词留英文,emoji 章节标题。
---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 78 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 3dfeb32..017fdd1 100644
--- a/README.md
+++ b/README.md
@@ -136,7 +136,11 @@ FuelLog/
 │   ├── public/                 # favicon / manifest / PWA icons
 │   └── package.json
 │
-├── deploy/                     # (待) docker-compose + nginx
+├── deploy/                     # Docker 部署文件
+│   ├── docker-compose.yml      # 生产:api + web(nginx),宿主机 :8080
+│   ├── docker-compose.dev.yml  # 开发:api 容器 + bind mount 本地 dist
+│   ├── nginx/web.conf          # web 容器用 nginx 配置(/api 反代 + SPA fallback)
+│   └── README.md               # 部署说明
 ├── docs/
 │   └── api.md                  # 完整 API 文档
 ├── data/                       # SQLite 文件(默认 .gitignore,挂载 volume)
@@ -168,15 +172,80 @@ FuelLog/
 
 ---
 
-## 🐳 部署(待完成)
+## 🐳 部署
+
+生产一条命令起 api + web,数据持久化到 named volume,前置 Nginx Proxy Manager
+或 Traefik 接 SSL 即可对外。
+
+### 快速部署
 
 ```bash
-cd deploy
-docker compose up -d
-# 浏览器访问 http://your-host
+# 在仓库根跑(任选一种)
+docker compose -f deploy/docker-compose.yml up -d
+# 浏览器访问 http://your-host:8080
 ```
 
-详见 `deploy/` 目录(待补充)。
+### 部署拓扑
+
+```
+┌─────────────────┐     ┌─────────────────┐
+│ Nginx Proxy Mgr │────▶│ fuellog-web:80  │
+│ (TLS / 反代)    │     │  (nginx:alpine) │
+└─────────────────┘     │  ├ 静态 SPA      │
+                        │  └ /api/* → api │
+                        └────────┬────────┘
+                                 │ fuellog-net
+                        ┌────────▼────────┐
+                        │ fuellog-api:8080│
+                        │  (golang alpine)│
+                        │  ├ GORM + SQLite │
+                        │  └ /data 卷      │
+                        └─────────────────┘
+```
+
+### 镜像要点
+
+| 镜像 | 基础 | 关键配置 |
+|---|---|---|
+| `fuellog/api` | 多阶段 `golang:1.22-alpine` → `alpine:3.20` | CGO=0 出纯静态二进制 / tini 收僵尸 / 非 root / 时区 Asia/Shanghai / HEALTHCHECK |
+| `fuellog/web` | 多阶段 `node:20-alpine` → `nginx:1.27-alpine` | corepack 启 pnpm / `pnpm build` → nginx 静态 / gzip + 30 天 immutable cache |
+
+### 数据持久化
+
+- 容器内 `DB_PATH=/data/fuellog.db`
+- 宿主机 docker volume 名:`fuellog-data`
+- 容器删了重建,数据还在;真正要备份:`docker run --rm -v fuellog-data:/data -v $(pwd):/backup alpine cp /data/fuellog.db /backup/`
+
+### 反代建议(不要直接把 8080 暴露公网)
+
+```
+Internet ──TLS──▶ Nginx Proxy Manager ──127.0.0.1:8080──▶ fuellog-web (容器)
+```
+
+容器只 listen 8080,不直接对外,符合 plan §17 "容器内 API 默认只监听内网"。
+
+### 健康检查
+
+- api:`wget http://127.0.0.1:8080/health`,30s 间隔,启动 10s 后开始
+- web:`wget http://127.0.0.1/`,30s 间隔
+- docker-compose 用 `depends_on: condition: service_healthy` 保证 web 等 api 健康后才起
+
+### 开发模式(不想本地装 Go 时用)
+
+```bash
+# 1. 本地 build 前端
+cd fuellog-web && pnpm install && pnpm build
+
+# 2. 启容器(nginx bind mount 上面 build 出的 dist)
+cd .. && docker compose -f deploy/docker-compose.dev.yml up
+
+# 3. 改前端 -> pnpm build -> docker compose restart web
+```
+
+日常前端调试还是推荐直接 `pnpm dev`(Vite :5173 自带 /api 代理),上面这套
+是为了"不想在 Windows 装 Go 也能跑后端"准备的。
+
+详细配置在 [`deploy/README.md`](./deploy/README.md)。
 
 ---
 
@@ -185,9 +254,9 @@ docker compose up -d
 - [x] Phase 0~1:初始化 + 后端骨架 + 数据层 + API + 单测 + 冒烟
 - [x] Phase 2~3:前端骨架 + 4 个业务页
 - [x] Phase 4:PWA(manifest / SW / 添加到主屏)
-- [ ] Phase 5:数据导入导出(JSON / CSV)
-- [ ] Phase 6:多用户 / 鉴权(目前是个人单机)
-- [ ] Phase 7:Docker 部署 + 反代
+- [x] Phase 5:Docker 部署 + 反代(API / web 多阶段镜像 + nginx + volume)
+- [ ] Phase 6:数据导入导出(JSON / CSV)
+- [ ] Phase 7:多用户 / 鉴权(目前是个人单机)
 - [ ] Phase 8:充电 / 保养 / 停车等扩展
 
 ---