跳到主要内容

FreeKitModules 部署

:::info 内容边界 本页与“可观测性”章节记录 FreeKitModules 当前仓库的部署方式。侧边栏中的“通用 Docker 部署参考”是独立基础教程，不代表本项目采用的镜像版本、端口或 Compose 配置；部署本项目时以本页和仓库中的 build/ 文件为准。 :::

仓库提供两组互相独立的 Compose：

目录部署内容
build/compose/freekit_pro_modules/MySQL、Redis、RabbitMQ、MeiliSearch、Host、Job、Message
build/observability/OpenObserve、OpenTelemetry Collector、Pyroscope、MySQL/Redis exporter

业务 Compose 不包含 Auth Host、HealthChecks UI 或可观测性平台；可观测性 Compose 也不会自动启动业务服务。两组需要通信时，共用 external Docker network freekit-net。

本地一键运行​

1. 准备环境文件​

业务 Compose 使用 build/compose/freekit_pro_modules/.env。一键脚本优先读取同目录的 .env.local，不存在时回退到 .env。建议复制为私有覆盖文件并修改密码：

Copy-Item build/compose/freekit_pro_modules/.env `
  build/compose/freekit_pro_modules/.env.local
cp build/compose/freekit_pro_modules/.env \
  build/compose/freekit_pro_modules/.env.local

不要把生产密码、连接字符串或第三方密钥提交到 Git。

2. 启动​

Windows：

build\run_freekit_pro_modules.bat

Linux/macOS：

bash build/run_freekit_pro_modules.bash

两个脚本最终都调用当前仓库的 docker-compose.yml 并执行 up -d --build。

3. 访问​

仓库当前 .env 的默认端口如下；如果修改过环境文件，以实际值为准。

服务默认地址
主 APIhttp://localhost:18080/kit_api
Swagger UIhttp://localhost:18080/kit_api/swagger
RapiDochttp://localhost:18080/kit_api/r
主健康检查http://localhost:18080/kit_api/health
Jobhttp://localhost:18081/job_api
Messagehttp://localhost:18082/message_api
RabbitMQ Managementhttp://localhost:15673
MeiliSearchhttp://localhost:17700

Compose 内部三个 .NET 容器都监听 8080，宿主机端口由 HOST_API_PORT、JOB_API_PORT、MESSAGE_API_PORT 映射。

只启动基础设施​

本地用 dotnet run 调试时，可以只启动依赖：

docker compose \
  --env-file build/compose/freekit_pro_modules/.env.local \
  -f build/compose/freekit_pro_modules/docker-compose.yml \
  up -d mysql redis rabbitmq meilisearch

若没有 .env.local，将命令中的路径改为 .env。

日常运维​

以下命令先设置两个路径，避免在错误目录操作：

COMPOSE_FILE=build/compose/freekit_pro_modules/docker-compose.yml
ENV_FILE=build/compose/freekit_pro_modules/.env.local

查看状态和日志：

docker compose --env-file "$ENV_FILE" -f "$COMPOSE_FILE" ps
docker compose --env-file "$ENV_FILE" -f "$COMPOSE_FILE" logs --tail 200 host
docker compose --env-file "$ENV_FILE" -f "$COMPOSE_FILE" logs --tail 200 job message

重新构建一个宿主：

docker compose --env-file "$ENV_FILE" -f "$COMPOSE_FILE" up -d --build host

停止但保留数据卷：

docker compose --env-file "$ENV_FILE" -f "$COMPOSE_FILE" down

down -v 会删除 MySQL、Redis、RabbitMQ 和 MeiliSearch 的 Compose 数据卷，只能在明确需要清空数据且已有备份时执行。

Compose 中的关键约定​

  • MySQL 初始化脚本：build/compose/freekit_pro_modules/mysql-init/01-create-databases.sql。
  • 敏感词文件以目录/文件挂载方式提供给 Host。
  • Host 使用 /kit_api，Job 使用 /job_api，Message 使用 /message_api。
  • MeiliSearch 在 Compose 中启用，并通过服务名 meilisearch:7700 访问。
  • RabbitMQ 连接和 vhost 由环境变量注入，不能只修改容器默认用户。
  • 业务 Compose 目前只给 Host 传入 OpenTelemetry 环境变量；Job/Message 如需导出，应在部署配置中分别补齐。

生产发布入口​

文件作用
build/build_and_push.sh构建并推送镜像
build/deploy_freekit_host.bash部署主 Host
build/deploy_job_host.bash部署 Job Host
build/deploy_message_host.bash部署 Message Host
build/deploy_auth_host.bash部署 Auth Host
build/deploy_on_server.sh服务器侧拉取并替换主 API 容器
build/trigger-kit-api.ps1触发 API 发布流水线

这些脚本面向当前项目环境，运行前必须审计镜像仓库、容器名、网络、端口、挂载目录和 Secret 来源。不要把示例中的服务器参数直接当成通用模板。

反向代理​

反向代理必须保留 PathBase。例如主 API 暴露在 /kit_api 时，健康检查、Swagger JSON、Swagger UI 和 RapiDoc 都位于此前缀下。若在代理层剥离前缀，应同时调整 ASPNETCORE_PATHBASE 和 Swagger endpoint，否则页面能打开但文档 JSON 会 404。

验证清单​

  1. docker compose ps 中依赖服务与三个 Host 均为预期状态。
  2. 访问 /kit_api/health，检查 MySQL、Redis、RabbitMQ 等依赖。
  3. 打开 /kit_api/swagger，确认 identity、plat、cms、cms-admin 分组可加载。
  4. 访问一个普通 API，确认认证、数据库和日志链路正常。
  5. 开启遥测时检查 Collector；仅访问 /health 不能验证 Trace，因为它在应用侧被过滤。

相关文档​