跳转至

配置

本项目的配置主要集中在 ai_service/utils/settings.py、根目录 config.toml 与 ai_service/utils/models.json。 敏感信息（如数据库密码）仅通过 .env 或环境变量配置，不写入 config.toml。

配置加载顺序

  1. 根目录 .env 会被 ai_service.utils.settings 自动加载。
  2. 若存在 ai_service/.env，会被模型加载器读取（override=False，不会覆盖系统环境变量）；容器部署建议优先使用平台环境变量或根目录 .env 注入。
  3. 根目录 config.toml 用于非敏感配置（如数据库 host、port、dbname）；可通过环境变量 CONFIG_FILE 指定其它路径。
  4. ai_service/.env.example 提供推荐字段模板。
  5. 运行时传入的参数（例如 API 请求中的 model_name / model_provider）优先级最高。

config.toml（非敏感配置）

  • 位置：项目根目录 config.toml（与 pyproject.toml 同级）。可复制 config.toml.example 为 config.toml 后修改。
  • 用途：存放数据库等非敏感配置，例如 [database] 下的 backend、host、port、name、driver。不包含用户名、密码。
  • 数据库密码：仅通过环境变量 POSTGRES_USER、POSTGRES_PASSWORD 或完整连接串 DATABASE_URL 在 .env 或环境中设置。

数据库连接优先级

  1. 最高：若已设置环境变量 DATABASE_URL，直接使用，不再读取 TOML 的 [database]。
  2. 其次：若 config.toml 中存在 [database] 且 backend = "postgresql"，则用 TOML 中的 host/port/name/driver 与环境变量 POSTGRES_USER、POSTGRES_PASSWORD 拼装 PostgreSQL 连接串。
  3. 默认：无 TOML 时，使用默认 PostgreSQL 本地连接（postgresql+psycopg2://localhost:5432/chameleon_meta）。

常用环境变量

以下配置项由 Config 读取（完整字段见 API 参考）：

  • LOG_LEVEL：日志级别（默认 INFO）。
  • APP_NAME：日志器名称（默认 app）。
  • APP_ENV：运行环境标识（development / staging / production）。
  • APP_INSTANCE：实例标识（用于区分同机多套部署）。
  • ENV_GUARD_MODE：环境保护模式（off / warn / strict）。
  • EXPECTED_PUBLIC_HOSTS：允许访问的外部 Host 白名单（推荐逗号分隔；也兼容 JSON 数组字符串；支持 https://... 输入，运行时会归一化为 hostname）。
  • CORS_ALLOWED_ORIGINS：ai-service 的 CORS 来源白名单（推荐逗号分隔，例如 https://admin.example.com,http://localhost:5173；也兼容 JSON 数组字符串；设置为 * 表示允许任意来源）。
  • DATABASE_URL：数据库连接字符串。未设置时由 config.toml 的 [database] 与 POSTGRES_USER/POSTGRES_PASSWORD 拼装，或默认连接本地 PostgreSQL。
  • POSTGRES_USER、POSTGRES_PASSWORD：与 config.toml 的 [database] 配合使用时的数据库凭据（仅 PostgreSQL）。
  • MINIO_ENDPOINT：ai-service 访问 MinIO 的内部地址（例如 minio:9000）。
  • MINIO_PUBLIC_ENDPOINT：生成预签名下载链接时使用的外部地址（例如 minio.example.com 或 https://minio.example.com）；未配置时回退为 API 代理下载。
  • MINIO_PUBLIC_SECURE：预签名下载链接是否使用 HTTPS（true/false）。
  • MINIO_PRESIGNED_EXPIRES_SECONDS：预签名下载链接过期时间（秒），默认 86400。
  • CHAT_MODEL_NAME：默认聊天模型名称。
  • CHAT_MODEL_PROVIDER：默认模型提供商。
  • CHAT_MODEL_TEMPERATURE：默认温度。
  • EMBEDDING_PROVIDER：Embedding 提供商（sentence_transformers 或 dashscope）。
  • EMBEDDING_BACKEND_TYPE：Embedding 后端类型（api 或 local，默认 api）。
  • EMBEDDING_MODEL：Embedding 模型名称。
  • EMBEDDING_DIM：Embedding 维度。
  • RERANK_ENABLED：是否启用检索后重排。
  • RERANK_MODEL：重排模型（默认 qwen3-rerank）。
  • BACKUP_MODE：备份模式（hot / cold / all）。
  • BACKUP_COMPOSE_FILE：备份脚本使用的 Compose 文件路径。
  • BACKUP_LOCAL_STAGE_DIR：备份临时工作目录。
  • BACKUP_LOCAL_ARCHIVE_DIR：备份归档目录。
  • BACKUP_REMOTE_DIR：远端/第二副本目录（可选）。
  • BACKUP_REMOTE_RSYNC_TARGET：通过 rsync 推送的远程目标（可选）。
  • BACKUP_RETENTION_DAYS：备份保留天数（默认 30）。
  • BACKUP_ENCRYPTION_ENABLED：是否启用归档加密（默认 true）。
  • BACKUP_KEEP_PLAINTEXT_ARCHIVE：加密后是否保留明文归档（默认 false）。
  • BACKUP_COLD_STOP_SERVICES：冷备时是否自动停止 postgres/minio/qdrant（默认 true）。
  • BACKUP_RESTORE_PREFER_COLD：恢复时优先使用冷备卷快照（默认 false）。
  • BACKUP_HEALTHCHECK_URL：恢复完成后的健康检查地址（默认 http://localhost:8000/healthz）。
  • BACKUP_ENCRYPTION_PASSPHRASE：备份归档加密口令（建议仅放在密钥管理系统）。

备份配置建议（非敏感放 TOML）

建议将以下非敏感备份配置放在 config.toml 的 [backup]：

[backup]
mode = "all"
compose_file = "docker-compose.infra.yml"
local_stage_dir = "data/backups/stage"
local_archive_dir = "data/backups/archive"
remote_dir = ""
remote_rsync_target = ""
retention_days = 30
encryption_enabled = true
keep_plaintext_archive = false
cold_stop_services = true
restore_prefer_cold = false
healthcheck_url = "http://localhost:8000/healthz"
restore_report_dir = "data/backups/restore-reports"

优先级说明（备份脚本）：

  1. 命令行参数（如 --mode）
  2. 环境变量（BACKUP_*）
  3. config.toml [backup]
  4. 脚本内默认值

远程复制规则：

  • 只有在 skip_remote_copy = false 且 remote_dir 或 remote_rsync_target 至少配置一个时，才会执行远程复制。
  • 若两者都为空，只会生成本地归档。

CI/CD 配置（GitHub Actions）

CI/CD 的运行配置主要来自 GitHub Secrets 与 Repository Variables，不应写入仓库文件。

必需 Secrets（发布链路）

  • REGISTRY_USERNAME：远程镜像仓库 registry.zata.cafe 登录用户名
  • REGISTRY_PASSWORD：远程镜像仓库 registry.zata.cafe 登录密码
  • DOKPLOY_API_KEY：Dokploy API Key（用于更新 compose 环境变量）
  • DOKPLOY_STAGING_DEPLOY_HOOK：staging 发布触发 hook
  • DOKPLOY_PROD_DEPLOY_HOOK：生产发布触发 hook
  • PROD_HEALTHCHECK_URL：生产发布后的健康检查地址

可选 Secrets（兜底）：

  • DOKPLOY_API_BASE_URL：Dokploy API 基础地址（例如 https://dokploy.example.com/api）
  • DOKPLOY_STAGING_COMPOSE_ID：staging compose ID（当 deploy hook 最后一段不是 composeId 时使用）
  • DOKPLOY_PROD_COMPOSE_ID：production compose ID（当 deploy hook 最后一段不是 composeId 时使用）

说明：CD 会优先从 DOKPLOY_STAGING_DEPLOY_HOOK / DOKPLOY_PROD_DEPLOY_HOOK 自动解析 composeId 与 API base（.../api）；若遇到 Compose not found，请补充 DOKPLOY_STAGING_COMPOSE_ID / DOKPLOY_PROD_COMPOSE_ID。DOKPLOY_API_BASE_URL 仅作 API base 兜底，并会自动规范为 .../api。

补充：CD 会校验 staging/prod 的 deploy hook 与 compose ID 不可相同，并在更新 compose env 时写入/校验 APP_ENV、APP_INSTANCE、ENV_GUARD_MODE、EXPECTED_PUBLIC_HOSTS。

Repository Variable

  • IMAGE_NAMESPACE：镜像命名空间，默认 aibot。

镜像命名规则

CD 工作流默认推送以下形式的镜像：

registry.zata.cafe/<IMAGE_NAMESPACE>/<service>:<GIT_SHA>

其中 <service> 包含：

  • ai-service
  • demo-backend
  • demo-frontend
  • admin-frontend
  • docs-site

Bases: BaseSettings

应用主配置 - 聚合所有子配置。

属性：

名称 类型 描述
app_name str

应用名称。
log_level str

日志级别。
app_env Literal['development', 'staging', 'production']

运行环境标识。
app_instance str

运行实例标识。
env_guard_mode EnvironmentGuardMode

环境保护模式（off/warn/strict）。
expected_public_hosts list[str]

允许访问的外部 Host 白名单。
cors_allowed_origins list[str]

CORS 允许来源（支持逗号分隔字符串或 list 输入）。
postgres_user str

PostgreSQL 用户名。
postgres_password SecretStr

PostgreSQL 密码。
database_url str

完整数据库 URL 覆盖。
minio_access_key str

MinIO 访问密钥。
minio_secret_key SecretStr

MinIO 密钥。
minio_root_user str

Docker MinIO root 用户。
minio_root_password SecretStr

Docker MinIO root 密码。
database DatabaseSettings

数据库子配置。
chat_model ChatModelSettings

聊天模型子配置。
minio MinioSettings

MinIO 子配置。
qdrant QdrantSettings

Qdrant 子配置。
embedding EmbeddingSettings

Embedding 子配置。
rerank RerankSettings

Rerank 子配置。
chunking ChunkingSettings

分块子配置。
timeouts TimeoutSettings

超时子配置。
mcp MCPSettings

MCP 出站能力配置。
agent_types AgentTypesSettings

智能体类型配置。
base_dir Path

项目根目录。
log_dir Path

日志目录。
log_file Path

日志文件路径。

resolved_database_url property 

resolved_database_url

解析最终 DATABASE_URL：env var > TOML + credentials > default。

返回：

名称 类型 描述
str str

最终的数据库连接 URL。

resolved_minio_access_key property 

resolved_minio_access_key

MinIO access key: MINIO_ACCESS_KEY > MINIO_ROOT_USER > default。

返回：

名称 类型 描述
str str

解析后的 MinIO access key。

resolved_minio_secret_key property 

resolved_minio_secret_key

MinIO secret key: MINIO_SECRET_KEY > MINIO_ROOT_PASSWORD > default。

返回：

名称 类型 描述
str str

解析后的 MinIO secret key。

ensure_log_directory 

ensure_log_directory()

确保日志目录存在。

引发：

类型 描述
OSError

当无法创建目录时抛出。

settings_customise_sources classmethod 

settings_customise_sources(settings_cls, **kwargs)

配置源优先级：env vars > .env > TOML [app] > defaults。

嵌套子模型各自读取 config.toml 对应 section。

参数：

名称 类型 描述 默认
settings_cls type[BaseSettings]

Settings 类。

 必需
**kwargs Any

默认源参数。

 {}

返回：

类型 描述
tuple[Any, ...]

tuple[Any, ...]: 配置源元组，按优先级排列。

MCP 配置（出站能力）

可在 config.toml 中新增 [mcp]，用于控制出站 MCP 能力：

[mcp]
enabled = true
max_tool_rounds = 3
default_timeout_ms = 10000
default_max_calls_per_turn = 3
default_encryption_key_id = "mcp-key-v1"

建议通过环境变量提供密钥：

  • MCP_SECRET_KEY：MCP 凭据加密主密钥（必填，生产环境必须覆盖默认值）
  • MCP_DEFAULT_ENCRYPTION_KEY_ID：默认密钥版本标识
  • MCP_REDACT_KEYS：审计脱敏关键字数组（推荐逗号分隔，也兼容 JSON 数组字符串）

说明：secret_key 不应写入 config.toml，应放在 .env 或部署环境密钥管理系统中。

模型配置（models.json）

  • 路径：ai_service/utils/models.json
  • 内容：提供商与模型列表、可选 api_key_env、base_url 等信息。
  • 当模型名称在多个提供商中重复时，建议显式传入 provider。

Embedding / Rerank 类别约束

  • Embedding 模型必须属于 text_embeddings 类别。
  • Rerank 模型必须属于 rerank_models 类别。
  • 若误将 qwen3-rerank 配置到 [embedding].model，启动或首次加载时会抛出明确错误。

推荐配置模板

在线（DashScope）

[embedding]
backend_type = "api"
provider = "dashscope"
model = "text-embedding-v4"
dim = 1536
offline_mode = false
model_dir = "resources/models"

[rerank]
enabled = true
provider = "dashscope"
model = "qwen3-rerank"
top_k = 20

离线（SentenceTransformers）

[embedding]
backend_type = "local"
provider = "sentence_transformers"
model = "sentence-transformers/all-MiniLM-L6-v2"
dim = 384
offline_mode = true
model_dir = "resources/models"

[rerank]
enabled = false

Qdrant 安全迁移配置

为避免 embedding 维度切换时覆盖旧向量，建议开启指纹集合命名：

[qdrant]
collection_name = "document_vectors"
use_embedding_fingerprint_collection = true
dual_read_enabled = false
read_fallback_collection_names = []

切换阶段可启用灰度双读：

[qdrant]
dual_read_enabled = true
read_fallback_collection_names = [
  "document_vectors__sentence-transformers-all-minilm-l6-v2__384"
]

当 [embedding] 中出现未知字段时，系统会输出 warning（包含 section 与字段名），避免静默失效。

补充：QDRANT_READ_FALLBACK_COLLECTION_NAMES 作为环境变量时，推荐使用逗号分隔（如 a,b），也兼容 JSON 数组字符串（如 ["a","b"]）。

如需自定义模型清单，可通过 config_path 参数覆盖默认路径。

日志与数据库

  • 日志输出：控制台 + logs/app.log。
  • 数据库：通过 config.toml 或 DATABASE_URL 配置 PostgreSQL 连接；未配置时默认连接本地 PostgreSQL。

如需覆盖连接，请在 .env 中设置 DATABASE_URL 或调整 config.toml 与 LOG_LEVEL 等配置项。