配置参考

两种配置方式

方式	适用场景	优先级
环境变量（推荐）	Docker 启动时通过 -e 传入，敏感信息不落盘	高
config.yaml	配置项多时用文件管理，挂载进容器	低

两者可以混用，环境变量会覆盖 yaml 中的同名配置。

快速参考：最常用的配置

大多数情况下你只需要改这几个：

docker run -d \
  -e ZIPOLY__SERVER__API_KEY=你的密钥 \          # 必填！API 访问密码
  -e ZIPOLY__LICENSE__KEY=你的License-Key \       # 可选，购买后填入
  -e ZIPOLY__QUEUE__MAX_CONCURRENT=10 \           # 并发任务数（内存大可调高）
  -e ZIPOLY__STORAGE__RETENTION_HOURS=24 \        # 文件保留时长（小时）
  zipoly-server:2.1.0

全部配置项

服务设置（server）

环境变量	默认值	说明
ZIPOLY__SERVER__HOST	0.0.0.0	监听地址，一般不用改
ZIPOLY__SERVER__PORT	8080	容器内端口，一般不用改（对外端口由 -p 控制）
ZIPOLY__SERVER__API_KEY	(必填)	API 密钥。所有请求都必须带这个 Key，相当于服务密码
ZIPOLY__SERVER__RATE_LIMIT_PER_MINUTE	60	每个 Key 每分钟最多请求次数。防止被滥用

存储（storage）

环境变量	默认值	说明
ZIPOLY__STORAGE__BACKEND	local	存储方式：local（本地磁盘）或 s3（对象存储）
ZIPOLY__STORAGE__RETENTION_HOURS	24	上传的文件和处理结果保留多久后自动清理（小时）

文件清理机制

处理结果默认保留 24 小时后自动删除。如果团队下载不及时可能会丢文件，建议：

• 内网使用：设为 168（一周）
• 对外服务：保持 24 或更短

任务队列（queue）

环境变量	默认值	说明
ZIPOLY__QUEUE__MAX_CONCURRENT	10	同时处理的任务数量。服务器内存大（8G+）可调到 20-30
ZIPOLY__QUEUE__TASK_TIMEOUT_SECONDS	600	单个任务最大执行时间（秒），超时自动终止。大模型可能需要更长

授权（license）

环境变量	默认值	说明
ZIPOLY__LICENSE__KEY	空	License Key，购买后填入。留空则使用试用模式
ZIPOLY__LICENSE__TRIAL_ENABLED	true	是否允许试用模式。设为 false 可强制要求授权才能用

试用模式的限制见授权与定价。

日志（logging）

环境变量	默认值	说明
ZIPOLY__LOGGING__LEVEL	info	日志级别：debug（最详细）→ info → warn → error（最少）
ZIPOLY__LOGGING__FORMAT	json	输出格式：json（结构化，方便日志系统收集）或 text（人眼可读）

排查问题时临时改为 debug：

-e ZIPOLY__LOGGING__LEVEL=debug -e ZIPOLY__LOGGING__FORMAT=text

用 config.yaml 配置（高级）

当配置项较多时，可以用 YAML 文件统一管理：

# config.yaml
server:
  host: "0.0.0.0"
  port: 8080
  api_key: "your-secure-api-key"     # 必填
  rate_limit_per_minute: 60

storage:
  backend: "local"                   # local 或 s3
  retention_hours: 24                # 文件保留时间（小时）
  local:
    upload_dir: "/tmp/uploads"
    result_dir: "/tmp/results"

queue:
  max_concurrent: 10                  # 并发数
  task_timeout_seconds: 600           # 超时时间（秒）

license:
  key: ""                            # License Key（可选）
  trial_enabled: true                # 允许试用
  trial_state_path: "./data/trial_state.json"

logging:
  level: "info"                      # debug / info / warn / error
  format: "json"                     # json / text
  file_path: null                    # 留空 = 只输出到控制台

挂载到容器中：

docker run -d \
  -v ./config.yaml:/app/config.yaml:ro \
  ...其他参数...

:ro 表示只读挂载，容器内无法修改该文件。

S3 对象存储（可选）

当需要跨服务器共享存储或数据量很大时，可以改用 S3 兼容存储（如 MinIO、阿里云 OSS）：

-e ZIPOLY__STORAGE__BACKEND=s3 \
-e ZIPOLY__STORAGE__S3__ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com \
-e ZIPOLY__STORAGE__S3__BUCKET=my-zipoly-bucket \
-e ZIPOLY__STORAGE__S3__ACCESS_KEY_ID=AKxxx \
-e ZIPOLY__STORAGE__S3__SECRET_ACCESS_KEY=SKxxx \
-e ZIPOLY__STORAGE__S3__REGION=cn-hangzhou

调优建议

场景一：团队日常使用（5-10 人）

-e ZIPOLY__QUEUE__MAX_CONCURRENT=5 \
-e ZIPOLY__STORAGE__RETENTION_HOURS=168   # 保留一周

场景二：CI/CD 流水线集成

-e ZIPOLY__QUEUE__MAX_CONCURRENT=2 \
-e ZIPOLY__QUEUE__TASK_TIMEOUT_SECONDS=300 \
-e ZIPOLY__STORAGE__RETENTION_HOURS=4      # 流水线会立即取走结果

场景三：大批量处理（100+ 文件/天）

-e ZIPOLY__QUEUE__MAX_CONCURRENT=20 \
-e ZIPOLY__LOGGING__LEVEL=warn            # 减少日志量