CatWiki 文档

Appearance

CatWiki 环境变量参考手册 ​

本文档提供 CatWiki 系统中所有环境变量的穷举说明。文档结构与 backend/.env.example 完美同步，确保配置与文档的高度一致性。

1. 基础环境配置 (Global Settings) ​

变量名描述默认/示例值生产建议
ENVIRONMENT运行环境模式local, dev, prod必须设为 prod
DEBUG是否开启调试模式true, false生产必须设为 false
LOG_LEVEL日志详细级别INFO可选: DEBUG, WARNING, ERROR
PROJECT_NAME系统显示名称CatWiki API-
DESCRIPTION系统详细描述CatWiki 后端服务-
VERSION当前 API 版本0.0.4-
API_V1_STR客户端 API 路由基地址/v1-
ADMIN_API_V1_STR管理后台 API 路由基地址/admin/v1-

2. 数据库配置 (PostgreSQL / PGVector) ​

变量名描述默认值备注
POSTGRES_SERVER数据库主机地址postgresDocker 部署请填容器名
POSTGRES_PORT数据库端口5432-
POSTGRES_DB数据库名称catwiki-
POSTGRES_USER数据库用户名postgres-
POSTGRES_PASSWORD数据库密码postgres必须修改
DB_ECHO输出 SQL 执行记录false调试 SQL 时开启
DB_POOL_SIZE连接池基础大小20高并发场景可调高
DB_MAX_OVERFLOW最大溢出连接数50-
DB_POOL_TIMEOUT获取连接超时 (秒)30-
DB_POOL_RECYCLE连接回收周期 (秒)3600-

3. 安全与访问控制 (Security & CORS) ​

变量名描述默认建议
SECRET_KEYJWT 令牌签名密钥必须修改 (openssl rand -hex 32)
ALGORITHMJWT 签名算法HS256
ACCESS_TOKEN_EXPIRE_MINUTES令牌有效期 (分钟)10080 (7 天)
BACKEND_CORS_ORIGINSCORS 域名白名单生产严禁使用 *

4. 对象存储配置 (RustFS / S3) ​

变量名描述示例/默认值
RUSTFS_ENDPOINT后端内部连接地址rustfs:9000
RUSTFS_ACCESS_KEY存储访问 Keyrustfsadmin
RUSTFS_SECRET_KEY存储访问 Secret必须修改
RUSTFS_BUCKET_NAME默认存储桶名称catwiki
RUSTFS_USE_SSL内部通信是否加密false
RUSTFS_REGION存储区域标识us-east-1
RUSTFS_ROOT_USERRustFS 初始化管理员名rustfsadmin
RUSTFS_ROOT_PASSWORDRustFS 初始化管理员密码rustfsadmin
RUSTFS_PUBLIC_URL前端访问文件基准 URLhttp://localhost:9000
RUSTFS_PUBLIC_BUCKET桶是否公共可读true

5. AI 模型服务配置 (OpenAI 兼容) ​

NOTE

AI 配置首次启动会同步到数据库。后续修改建议在管理后台进行，或设置 FORCE_UPDATE_AI_CONFIG=true 强制同步。

5.1 Chat 对话模型 ​

变量名描述示例值
AI_CHAT_API_KEY对话服务 API Keysk-xxxx
AI_CHAT_API_BASE对话服务 API 基地址https://api.openai.com/v1
AI_CHAT_MODEL对话模型名称gpt-4o, deepseek-chat

5.2 Embedding 向量服务 ​

变量名描述示例值
AI_EMBEDDING_API_KEY向量服务 API Keysk-xxxx
AI_EMBEDDING_API_BASE向量服务 API 基地址https://api.openai.com/v1
AI_EMBEDDING_MODEL向量模型名称text-embedding-3-small
AI_EMBEDDING_DIMENSION向量维度1536, 1024
AI_EMBEDDING_BATCH_SIZE批量处理数量10

5.3 Reranker 重排序 ​

变量名描述示例值
AI_RERANK_API_KEY重排服务 API Keysk-xxxx
AI_RERANK_API_BASE重排服务 API 基地址https://api.openai.com/v1
AI_RERANK_MODEL重排模型名称bge-reranker-v2-m3

5.4 VL 视觉/多模态模型 ​

变量名描述示例值
AI_VL_API_KEY视觉服务 API Keysk-xxxx
AI_VL_API_BASE视觉服务 API 基地址https://api.openai.com/v1
AI_VL_MODEL视觉模型名称gpt-4o

6. RAG 检索与智能 Agent 调优 ​

变量名描述默认值
RAG_RECALL_K初始向量召回数量50
RAG_RECALL_MAX全局召回文档块上限100
RAG_RECALL_THRESHOLD相似度召回阈值0.3
RAG_ENABLE_RERANK是否启用重排序精排true
RAG_RERANK_TOP_K最终呈现给 AI 的段落数5
AGENT_MAX_ITERATIONSAI 思考最大轮次5
AGENT_MAX_CONSECUTIVE_EMPTY连续空响应终止阈值2
AGENT_SUMMARY_TRIGGER_MSG_COUNT触发摘要的消息数10

7. 文档解析引擎 (DocProcessor) ​

7.1 MinerU (深度 PDF 解析) ​

变量名描述示例值
MINERU_ENABLED是否启用 MinerUtrue
MINERU_NAME服务显示名称MinerU
MINERU_BASE_URLMinerU API 基地址http://mineru-service:8888
MINERU_API_KEYMinerU API 访问密钥sk-mineru-key

7.2 Docling (通用文档解析) ​

变量名描述示例值
DOCLING_ENABLED是否启用 Doclingtrue
DOCLING_NAME服务显示名称Docling
DOCLING_BASE_URLDocling API 基地址http://docling-service:8000
DOCLING_API_KEYDocling API 访问密钥sk-docling-key

7.3 PaddleOCR (图片/扫描件 OCR) ​

变量名描述示例值
PADDLEOCR_ENABLED是否启用 PaddleOCRfalse
PADDLEOCR_NAME服务显示名称PaddleOCR
PADDLEOCR_BASE_URLPaddleOCR API 基地址http://paddleocr-service:8080
PADDLEOCR_API_KEYPaddleOCR API 访问密钥NONE

8. 系统限制与运维 (Limits & DevOps) ​

变量名描述默认值
UPLOAD_MAX_SIZE文件上传上限 (字节)104857600 (100MB)
UPLOAD_ALLOWED_EXTENSIONS允许上传的后缀列表PDF, DOCX, TXT...
FORCE_UPDATE_AI_CONFIG强制同步 AI 配置false
FORCE_UPDATE_DOC_PROCESSOR强制同步解析配置false

8.3 部署控制与端口映射 (Infrastructure Only) ​

IMPORTANT

以下变量仅用于 Docker Compose 容器端口到宿主机的映射。前端项目不再使用 .env 文件，其所有环境变量均通过 docker-compose.yml 中的 environment 块直接注入。修改配置后请重启容器生效。

变量名描述默认宿主机端口参考作用服务
BACKEND_PORT后端 API 对外端口3000backend
ADMIN_PORT管理后台对外端口8001admin-frontend
CLIENT_PORT演示问答端对外端口8002client-frontend
DOCS_PORT帮助文档站对外端口8003docs-frontend
WEBSITE_PORT官网首页对外端口8004website
RUSTFS_CONSOLE_PORTRustFS 后端管理端口9001rustfs

🎯 变量覆盖机制 ​

CatWiki 的配置加载顺序遵循 “高优先覆盖” 原则：

  1. Docker environment (在 Compose 文件的 environment 或 args 中定义)
  2. 生产环境 .env 文件 (deploy/docker/.env, 仅限后端应用)
  3. 开发环境 .env 文件 (backend/.env, 仅限后端应用)
  4. 代码硬编码默认值 (最后的退路)