fix(deploy): web.conf 移到 fuellog-web/ 自己的 build context

NAS 部署时 web 阶段失败: failed to solve: failed to compute cache key: "/deploy/nginx/web.conf": not found 根因:fuellog-web/Dockerfile 的 `COPY deploy/nginx/web.conf` 是相对 build context 的。web Dockerfile 的 context = fuellog-web/,所以它在找 fuellog-web/deploy/nginx/web.conf —— 实际文件在仓库根的 deploy/nginx/web.conf, 出 context 了,build 报错。修法:把 web.conf 移到 web 自己的 build context 内,放到 fuellog-web/nginx/web.conf。 Dockerfile COPY 改成 `COPY nginx/web.conf`。同时 deploy/docker-compose.dev.yml 的 bind-mount 路径从 ./nginx/web.conf 改成 ../fuellog-web/nginx/web.conf。 deploy/nginx/web.conf 保留为重定向注释占位,deploy/ 目录在 git 里仍是有效的,避免外部引用突然找不到。期间顺带:dev compose 之前 `./nginx/web.conf` 路径是相对 deploy/,符合 compose 的"相对 compose 文件找依赖"约定,改成 `../fuellog-web/nginx/web.conf` 也保持一致;prod compose 不动,它只 build 不直接挂文件。未做(留待后续): - 把 deploy/nginx/web.conf 直接 rm 掉(目前用"重定向注释"占位); PowerShell 没有 mavis-trash,删文件会被拦。后续可改用 .gitkeep + 真删流程,或干脆用符号链接 - fuellog-web/deploy/ 之类的隔离目录,等真正需要再说
2026-09-13 19:38:46 +08:00
parent 0a7d41e406
commit f9022e9419
4 changed files with 81 additions and 13 deletions
@@ -185,6 +185,35 @@ docker compose -f deploy/docker-compose.yml up -d
 # 浏览器访问 http://your-host:8080
 ```

+### 改端口(默认 8080 冲突时)
+
+如果宿主机 8080 已被占用(NAS、其它服务),用一个环境变量一起改 api
+内部监听 + web 容器 upstream + 宿主机映射:
+
+```bash
+# 例:把整套改成 8081
+API_PORT=8081 WEB_PORT=8081 \
+  docker compose -f deploy/docker-compose.yml up -d --build
+```
+
+`API_PORT` 控制:
+- `api.SERVER_ADDR`(api 容器内监听)
+- `api.expose` / `healthcheck`(容器间网络)
+- `web` build 阶段的 nginx upstream(`web.conf` 里 `server api:__API_PORT__` 在
+  build 时 sed 替换)
+
+`WEB_PORT` 控制宿主机到 web 容器 80 端口的映射。
+
+`.env` 文件也能放(放在仓库根,自动被 compose 读):
+
+```
+API_PORT=8081
+WEB_PORT=8081
+```
+
+> **改完端口不重 build 是不生效的**,因为 web 镜像里的 nginx conf 是
+> build 时定的。`up -d --build` 才能拿到新镜像。
+
 ### 部署拓扑

 ```
@@ -207,8 +236,8 @@ docker compose -f deploy/docker-compose.yml up -d

 | 镜像 | 基础 | 关键配置 |
 |---|---|---|
-| `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 |
+| `fuellog/api` | 多阶段 `golang:1.27-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 / `API_PORT` build arg 注入 upstream |

 ### 数据持久化

@@ -216,20 +245,44 @@ docker compose -f deploy/docker-compose.yml up -d
 - 宿主机 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 (容器)
+Internet ──TLS──▶ Nginx Proxy Manager ──127.0.0.1:WEB_PORT──▶ fuellog-web (容器)
 ```

-容器只 listen 8080,不直接对外,符合 plan §17 "容器内 API 默认只监听内网"。
+容器内 API 不直接对外,符合 plan §17 "容器内 API 默认只监听内网"。
+`WEB_PORT` 是宿主机 listen 端口(默认 8080),跟 `API_PORT`(容器内 api
+监听,默认 8080)是两个独立变量,大部分场景保持一致。

 ### 健康检查

- api:`wget http://127.0.0.1:8080/health`,30s 间隔,启动 10s 后开始
+- api:`wget http://127.0.0.1:${API_PORT}/health`,30s 间隔,启动 10s 后开始
 - web:`wget http://127.0.0.1/`,30s 间隔
 - docker-compose 用 `depends_on: condition: service_healthy` 保证 web 等 api 健康后才起

+### 排错:502 Bad Gateway
+
+最常见原因:`API_PORT` 与 `api` 容器实际 listen 端口不一致。
+
+`fuellog-web/nginx/web.conf` 里 upstream 写的是 `server api:__API_PORT__`,
+由 build 阶段用 `docker compose` 传入的 `API_PORT` 替换。如果改了
+`SERVER_ADDR` 端口但忘改 build arg,或者改了 build arg 但没重 build,
+nginx 就会 upstream 连不上返 502。
+
+排查步骤:
+```bash
+# 1. 看 api 实际 listen 端口
+docker exec fuellog-api sh -c 'wget -qO- http://127.0.0.1:8080/health 2>&1 || echo 8080_FAIL'
+docker exec fuellog-api sh -c 'wget -qO- http://127.0.0.1:8081/health 2>&1 || echo 8081_FAIL'
+
+# 2. 看 web 容器内 nginx conf 写的是哪个端口
+docker exec fuellog-web cat /etc/nginx/conf.d/web.conf | grep 'server api:'
+
+# 3. 不一致就重 build(只 up -d 不会重 build)
+API_PORT=8081 docker compose -f deploy/docker-compose.yml up -d --build
+```
+
 ### 开发模式(不想本地装 Go 时用)

 ```bash