 KennethCheng
|
7d5ab0a2ec
|
fix(deploy): API_PORT 端口模板化,web upstream 不再写死 8080
NAS 部署时 POST /api/vehicles 返 502 Bad Gateway,根因是 compose 改
SERVER_ADDR: ":8081" 但 fuellog-web/nginx/web.conf 里 upstream 还写死
server api:8080 → nginx upstream 连不上,web 容器把请求反代失败,返 502。
修法:把端口做成 build arg + sed 替换:
- fuellog-web/Dockerfile 加 `ARG API_PORT=8080` + `sed` 在 build 时把
web.conf 里的 __API_PORT__ 占位替换为真实端口
- deploy/docker-compose.yml:
* api.SERVER_ADDR 改成 `:${API_PORT:-8080}`(默认仍是 8080)
* api.expose / healthcheck 端口都改用 ${API_PORT:-8080}
* web build args 传 API_PORT,容器内 web 镜像就有了对的 upstream
* 新增 WEB_PORT 控制宿主机 → web 容器 :80 映射
- README 新增"改端口"小节,说明 API_PORT / WEB_PORT 用法;
新增"排错:502 Bad Gateway"小节,把这次踩的坑(改 SERVER_ADDR 忘
改 web upstream、忘重 build)写明,下次再撞就有现成排查路径
期间的小坑(都修了):
- web.conf 占位用 __API_PORT__(双下划线)而不是 ${API_PORT},避免
nginx 把它当成变量语法尝试解析
- docker-compose 用 ${API_PORT:-8080} 而不是裸 ${API_PORT},这样
用户不传环境变量也能跑(默认 8080)
- README 里 web/api 表格里"golang:1.22-alpine"也顺手改成 1.27-alpine
跟实际 Dockerfile 一致(上次 f81047f 提过但 README 漏了)
未做(留待后续):
- 端口改成可改 web upstream 后,理论上仍然可能出现 build-time / run-time
不一致(build args vs 环境变量);更稳的方案是给 web 加个 entrypoint 脚本,
启动时再 sed 一次 env 变量到 nginx conf —— 留到真有"频繁换端口"的
场景再做
- `.env.example` 没改,只加了 README 文档化的 .env 用法;compose 默认值
已经是 8080,本地 dev 不需要 .env
|
2026-09-13 19:39:19 +08:00 |
|
|
KennethCheng
|
a2fc215ef9
|
docs: README 补全 Docker 部署章节(拓扑图 / 镜像要点 / 持久化 / 反代)
上条 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 章节标题。
|
2026-09-13 17:20:50 +08:00 |
|
|
KennethCheng
|
f24e6639e3
|
docs: 仓库根 README + docs/api.md 完整 API 文档
补上交付物必备的文档:
- README.md:项目介绍 / 特性 / 技术栈 / 快速开始 / 仓库结构 /
核心计算公式 / 测试覆盖 / 设计原则 / 路线图 / License
- docs/api.md:6 个 endpoint 完整契约(请求参数 / 响应 / 错误码 /
业务规则),含 Statistics 字段含义与采样逻辑说明
为什么现在补:
- 之前的 12 个 commit 都是代码,GitHub / Gitea 仓库首页空白
- 新成员(或者未来的自己)来看仓库,无法在 5 分钟内知道这是个啥 / 怎么跑
- API 文档从代码里的 dto.go / handler.go 反推,容易漏边界条件;集中写一遍
把所有约束沉淀下来
README 设计:
- 顶上一段简介 + badge
- ✨ 特性(7 条,每条对应 plan §3 / §6 / §12)
- 🛠 技术栈:表格化展示 plan 锁定选型
- 🚀 快速开始:5 步(克隆 / 装依赖 / 启后端 / 启前端 / 冒烟)
- 📁 仓库结构:树状展示两个子工程的完整布局
- 🔢 核心计算规则:4 个公式表(从 plan §6 提炼)
- 🧪 测试覆盖:列出 22+5+13 的具体来源文件
- 🐳 部署 / 🗺 路线图:占位 + 标 done
- 📐 设计原则:把 plan §12 + AGENTS.md 关键约束翻译成"为什么这么做"
- 📎 相关:链回 AGENTS.md / docs/api.md / FuelLog_PLAN.md
docs/api.md 设计:
- 通用约定:UTC / decimal / 列表空数组 / 错误码字典
- 6 个 endpoint 一段一个,含:curl-style 示例、参数表、Response 200 示例、
业务规则(例如 RefuelCreate.price_per_liter 不入参 / RefuelUpdate
patch 语义 / Statistics 只在 is_full 序列内采样)
- 错误码字典表格(INTERNAL / INVALID_ARGUMENT / NOT_FOUND / CONFLICT / ...)
- 索引说明
风格:中文为主,与 AGENTS.md / commit message 保持一致;技术名词留英文
(endpoint / Vehicle / RefuelRecord 等);代码示例保持 JSON 风格。
未做(留待后续):
- README 截图:得真起服务跑,等 Docker 起来再补
- README 英文版:暂只中文,MVP 上线后再翻
|
2026-09-13 17:06:39 +08:00 |
|