Cheshire Cat AI 容器端口配置与日志显示不一致问题解析

在 Cheshire Cat AI 核心组件的容器化部署过程中，开发者可能会遇到一个看似微小但可能影响使用体验的问题：当在 docker-compose 配置文件中自定义了服务端口映射后，容器启动日志中显示的端口号并未同步更新，仍然显示默认值。

问题现象

当开发者修改 compose 配置文件中的端口映射设置，例如将默认的 1865:80 改为 1866:80 时，虽然容器能够正常启动并通过新端口访问服务，但启动日志中仍然显示默认的 1865 端口：

containerName_cat_core  | Cat REST API: http://localhost:1865/docs
containerName_cat_core  | Cat ADMIN: http://localhost:1865/admin

技术背景

这个问题的根源在于 FastAPI 应用本身无法自动感知容器对外暴露的端口映射关系。Cheshire Cat AI 在日志显示功能中，通过读取环境变量 CCAT_CORE_PORT 来获取应该显示的端口号。

解决方案

要解决这个显示不一致的问题，开发者需要在 docker-compose 配置中正确设置 CCAT_CORE_PORT 环境变量，使其与实际映射的外部端口保持一致。以下是推荐的配置方式：

services:
  cheshire-cat-core:
    image: ghcr.io/cheshire-cat-ai/core:latest
    environment:
      - CCAT_CORE_PORT=1866  # 与映射的外部端口一致
    ports:
      - 1866:80
      - 5676:5678

或者使用更灵活的变量替换语法：

services:
  cheshire-cat-core:
    image: ghcr.io/cheshire-cat-ai/core:latest
    environment:
      - CCAT_CORE_PORT=${CCAT_CORE_PORT:-1866}
    ports:
      - ${CCAT_CORE_PORT:-1866}:80

最佳实践建议

1. 环境变量管理：建议使用 .env 文件统一管理所有环境变量，包括端口配置
2. 多实例部署：当需要运行多个 Cheshire Cat AI 实例时，确保每个实例都有独立的端口配置和环境变量设置
3. 配置验证：部署后验证日志输出与实际访问地址是否一致
4. 文档参考：虽然本文不提供具体链接，但建议开发者参考官方文档中关于环境变量配置的部分

总结

这个看似简单的端口显示问题实际上反映了容器化应用配置管理的一个重要原则：应用需要明确的环境变量配置来适应不同的部署场景。通过正确设置 CCAT_CORE_PORT 环境变量，开发者可以确保日志信息与实际部署配置保持一致，特别是在多实例部署等复杂场景下，这种一致性尤为重要。