企业官网建设流程全解析

本文是 FlexPrice（基于用量计费与订阅管理的开源后端）Docker/Makefile 开发快捷方式的实操指南，围绕仓库内置的compose开发技能展开：如何一键完成首次环境搭建、如何按需启动核心后端服务与全栈、如何通过devprofile 拉起 Kafka UI、如何在多进程架构（API / Consumer / Worker）下查看日志排障，以及如何正确处理FLEXPRICE_*环境变量与容器 DNS 的对应关系。读完本文，你将掌握一套可复制的本地开发工作流，并能独立排查 "connection refused" 类的常见环境问题。

compose技能是什么：定位与触发方式

在 FlexPrice 仓库的.cursor/skills/目录下，以「技能（Skill）」形式沉淀了一批面向 AI 编码助手与开发者的工作流说明书，其中compose就是面向Docker / Makefile 快捷操作的速查手册（详见 .cursor/skills/README.md 中的技能总表）。

其 YAML frontmatter 明确了定位：

• name:compose
• description: FlexPrice Docker/Makefile shortcuts —— dev-setup、compose 服务编排、Kafka UI profile、日志查看。
• 触发词（Trigger）:compose、docker dev、dev-setup。

也就是说，当你在对话或编码助手语境中输入 "compose"、"docker dev" 或 "dev-setup" 时，应加载这份技能文档来指导操作。一个重要的职责边界是：本文档只负责"快捷命令"，而深度环境向导（modes、.env*细节、Kafka topic 坑、migrations）属于devenv技能。二者分工为：compose回答"用什么命令"，devenv回答"环境到底怎么配、哪里容易错"。

首次 / 完整环境搭建：make dev-setup

对于全新克隆的仓库，一条命令即可完成从基础设施到应用服务的完整开发环境：

make dev-setup

这条命令并非魔法，而是由 Makefile 中dev-setup目标编排的四个步骤，逐一拆解如下：

命令成功后会输出环境就绪信息，包括：

• 服务地址：APIhttp://localhost:8080、Temporal UIhttp://localhost:8088、Kafka UIhttp://localhost:8084（需--profile dev）、ClickHousehttp://localhost:8123；
• 默认本地 API Key：sk_local_flexprice_test_key，调用方式为请求头-H 'x-api-key: sk_local_flexprice_test_key'。

提示：make dev-setup是全量流程，适合首次搭建。日常开发若只需基础设施在线，可直接跳到下一节的轻量启动方式。

dev-setup依赖的flexprice-build服务在 docker-compose.yml 中被标记为profiles: ["build-only"]，是一个仅用于构建阶段的服务，其他flexprice-*服务都以image: flexprice-app:local复用这一镜像。因此当 Dockerfile 或依赖发生变化时，应重新构建镜像：

docker compose build flexprice-build # 或 make build-image

随后用make restart-flexprice让应用服务载入新镜像。

仅启动核心后端服务（基础设施子集）

如果应用进程打算在宿主机上以go run方式运行（hybrid 模式，这也是devenv技能默认推荐的形态），那么 Docker 只负责基础设施部分：

docker compose up -d postgres kafka clickhouse temporal temporal-ui

这条命令启动 docker-compose.yml 中定义的五个核心服务，各自的关键配置如下：

两点值得注意：

1. Kafka 的监听器分内外两套：容器内部走kafka:9092（INTERNAL），宿主机进程必须走localhost:29092（EXTERNAL，见 docker-compose.yml）。从宿主机 Go 二进制连kafka:9092会连接失败——这是最常见的坑之一。
2. temporal 强依赖 postgres：该 Compose 文件内的 Temporal 通过depends_on: postgres: service_healthy等待 Postgres 就绪，因此不能从本 Compose 中单独剥离 Postgres 而继续使用自带 Temporal。

另外，docker-compose.yml中还定义了redis（redis:7-alpine，127.0.0.1:6379，AOF 持久化开启），虽然它不在文档的核心服务列表里，但flexprice-api等应用服务同样depends_on它，本地缓存（Redis 缓存）依赖此容器。

全栈控制：make up/make down/make restart-flexprice

当希望连应用带基础设施全部跑在 Docker 里（完全容器化形态）时，使用全栈命令：

make up # 启动所有服务（docker compose up -d --build） make down # 停止所有服务（docker compose down） make restart-flexprice # 只重启应用服务，不动基础设施

对应关系可在 Makefile 与 Makefile 中找到：

• up=docker compose up -d --build：构建并后台启动所有服务；
• down=docker compose down：停止容器（不会删除数据卷，数据仍在postgres-data、kafka-data、clickhouse-data、redis-data卷中）；
• restart-flexprice=stop-flexprice+start-flexprice，其中：
  • start-flexprice只docker compose up -d flexprice-api flexprice-consumer flexprice-worker；
  • stop-flexprice只docker compose stop flexprice-api flexprice-consumer flexprice-worker。

flexprice-api、flexprice-consumer、flexprice-worker三个服务对应三种部署模式（docker-compose.yml）：

此外还有第四种模式local（单进程内同时运行 API、Consumer、Worker），对应宿主机上的make run-server/make run-local系列目标。这套按模式拆分的架构正是 FlexPrice 生产可横向扩展的基础，本地通过三个 Compose 服务即可一比一复现。

数据重置类命令（非文档正文，但常与全栈控制搭配使用）包括：

make clean-docker # docker compose down -v + 清理 flexprice 相关数据卷（破坏性操作） make clean-start # down -v 后重新 setup-local

执行前请确认当前环境可接受数据清空。

Kafka UI（dev profile）：可视化排查事件流

Kafka 在 FlexPrice 的事件计量、账单流水链路中处于核心位置，为了直观查看 topic 与消费情况，可启用 Kafka UI：

docker compose --profile dev up -d kafka-ui

启动后访问http://localhost:8084。这里的--profile dev对应 docker-compose.yml 中kafka-ui服务的profiles: ["dev"]声明——带 profile 的服务不会随docker compose up -d默认启动，必须显式加--profile dev才会拉起。kafka-ui使用ghcr.io/kafbat/kafka-ui:main镜像，连接kafka:9092（容器内网），并开启DYNAMIC_CONFIG_ENABLED。

在 Kafka UI 中可以完成以下日常排障动作：查看 topic 分区与消息积压（lag）、核对消费组 offset、验证make init-kafka创建的 topic 是否齐全。由于KAFKA_AUTO_CREATE_TOPICS_ENABLE=false，任何缺失 topic 都会导致生产/消费失败，UI 是发现这类问题最快的手段。

本地默认 URL 速查表

文档引用了 AGENTS.md 与 CLAUDE.md 中的端口表，本地默认地址汇总如下（与 docker-compose.yml 端口映射及 internal/config/config.yaml 默认值一致）：

调用 API 时注意base URL 必须带/v1（如http://localhost:8080/v1），本地调试默认 API Key 为sk_local_flexprice_test_key，请求头使用x-api-key。

调试：分进程查看容器日志

FlexPrice 将 API、Consumer、Worker 拆为独立进程后，日志也按服务隔离，排查问题时分别跟踪：

docker compose logs -f flexprice-api # API 服务日志 docker compose logs -f flexprice-consumer # Kafka 事件消费日志 docker compose logs -f flexprice-worker # Temporal Worker 日志

-f为 follow 模式，持续输出新日志。这三个服务恰好对应三种部署模式，因此：

• 收到 HTTP 请求类问题 → 看flexprice-api；
• 事件迟迟不计费/不落库 → 看flexprice-consumer（配合 Kafka UI 检查 topic 积压）；
• 账单周期、发票生成等长时间工作流异常 → 看flexprice-worker（同时可在 Temporal UI http://localhost:8088 查看 workflow 执行历史与失败详情）。

此外，直接进入容器交互式排查也是常见手段，例如：

docker compose exec postgres psql -U flexprice -d flexprice docker compose exec clickhouse clickhouse-client --user=flexprice --password=flexprice123 --database=flexprice docker compose exec -T kafka kafka-topics --bootstrap-server kafka:9092 --list

环境变量与 "connection refused" 排障：宿主进程 vs 容器进程

文档的 Notes 部分特别强调：排查连接被拒问题时，要让FLEXPRICE_*环境变量（或.env）与 Compose 服务的实际监听地址对齐。这一条是整个本地开发中最容易踩坑、也最值得展开的地方。

关键在于区分两种进程形态：

1. 容器内进程（Compose 服务）—— 直接使用 Docker 网络内的服务名：

以上值可直接在 docker-compose.yml 中看到，全部以FLEXPRICE_*前缀覆盖 internal/config/config.yaml 的默认值。

2. 宿主机 Go 进程（go run/make run-local-*）—— 绝不能使用postgres、kafka:9092这类 Docker 内部 DNS 名，必须显式指向回环地址（.cursor/skills/devenv/SKILL.md 中 §C1 的完整配置）：

FLEXPRICE_POSTGRES_HOST=127.0.0.1 FLEXPRICE_POSTGRES_PORT=5432 FLEXPRICE_POSTGRES_USER=flexprice FLEXPRICE_POSTGRES_PASSWORD=flexprice123 FLEXPRICE_POSTGRES_DBNAME=flexprice FLEXPRICE_POSTGRES_SSLMODE=disable FLEXPRICE_POSTGRES_READER_HOST=127.0.0.1 FLEXPRICE_POSTGRES_READER_PORT=5432 FLEXPRICE_KAFKA_BROKERS=localhost:29092 # 注意是 EXTERNAL 监听器端口 FLEXPRICE_CLICKHOUSE_ADDRESS=127.0.0.1:9000 FLEXPRICE_TEMPORAL_ADDRESS=127.0.0.1:7233

"connection refused" 的典型根因就是混用了两套地址：宿主机进程用了容器 DNS 名（postgres、kafka:9092、clickhouse:9000），或 Kafka 用了9092而非宿主侧的29092。排查顺序建议为：

1. docker compose ps确认服务均已启动且 healthy；
2. 核对正在运行的是容器进程还是宿主进程，分别按上表检查FLEXPRICE_*取值；
3. Kafka 走宿主进程时确认 broker 为localhost:29092；
4. 用curl -sf http://127.0.0.1:8123/ping、docker compose exec -T postgres pg_isready -U flexprice -d flexprice等探针逐项验证连通性。

关于.env的加载顺序，Makefile中run-local-*系列目标采用「先.env后.env.local、后者覆盖前者」的策略（见 Makefile），因此任何指向远端/容器 DNS 的旧值都可能被残留到.env中。排查时可用rg检查相关FLEXPRICE_(POSTGRES_|KAFKA_|CLICKHOUSE_|TEMPORAL_)的赋值（注意脱敏），并在.env.local中修正，而不是直接信任.env。

注意事项：不要在面向生产的 Compose override 中提交 secrets

文档最后一条 Note 是安全纪律：不要在面向生产环境的 Compose overrides 里提交 secrets。具体到本仓库：

• 本地开发的密钥（如FLEXPRICE_AUTH_API_KEY_KEYS中的 API Key 哈希、flexprice123等默认口令）仅存在于 docker-compose.yml 的本地开发配置中，其值来自.gitignore排除的.env/.env.local/.secrets；
• 部署到生产时，应通过部署平台的 Secret 机制注入FLEXPRICE_*环境变量，而不是把明文密钥写进 Compose 覆盖文件并提交到版本库；
• 同理，devenv技能也强调不得将.env/.env.local全文粘贴到对话记录中（会泄露口令/Token）。

相关技能：深度环境配置交给devenv

当遇到本文档范围之外的问题时，应转入深度环境向导devenv：

• 部署模式（local/api/consumer/temporal_worker）的选择与对应启动命令；
• .env/.env.local的正确维护、主机 vs 容器 DNS（§C1 / §C2）；
• Kafka topic 的创建纪律（默认 topic 列表、make init-kafka前必须征求确认、webhook.topic与 topic 列表不一致的风险）；
• 消费组隔离、环境验证循环（§F）与工作量分级（§M / §N）。

.cursor/skills/README.md还提到，仓库内的完整技能矩阵（arch、godev、devenv、compose、openapi、apitest、pr、gh）可组合成完整工作流：apitest（主）→devenv+compose（基础设施）→godev（单元测试）→arch+docs/FLOWS/（架构事实）。compose在其中扮演的是"最快拉起环境"的入口角色。

小结

compose技能用最少的命令覆盖了 FlexPrice 本地开发的全部日常操作：make dev-setup一键全量搭建、docker compose up -d按需启动基础设施、make up/down/restart-flexprice全栈控制、--profile dev拉起 Kafka UI、docker compose logs -f分进程排障，并明确了FLEXPRICE_*环境变量在容器内外两套取值体系。配合 Makefile、docker-compose.yml 与 internal/config/config.yaml 源码级对照，即可在几分钟内建立起可复现、可排障的 FlexPrice 开发环境。