Stacks配置项全解析:config.yaml每个参数与环境变量速查清单
Stacks配置项全解析:config.yaml每个参数与环境变量速查清单
Stacks 是一个专为 Anna's Archive 打造的轻量级下载管理器,支持高速下载、Web 界面和 API 调用。本文带你完整解析 Stacks 的配置文件 config.yaml 中每一个参数的含义、默认值与取值范围,并汇总 docker-compose.yml 里所有环境变量的速查清单,帮助新手一次配好 Stacks 配置。
一、config.yaml 文件在哪里?如何修改?
- 容器内位置:
/opt/stacks/config/config.yaml,通过卷挂载到宿主机的/path/to/config目录 - 首次启动:文件不存在时会自动创建,并根据环境变量写入初始配置
- 两种修改方式:
- Web 界面 Settings 标签页修改——立即生效,无需重启
- 直接编辑 config.yaml——需要重启服务
- 自动修复机制:Stacks 启动时会对照 files/config_schema.yaml 校验配置,非法值会自动回退为默认值(日志中提示 "config file has been healed"),改错也不怕
- 删除即重置:删掉 config.yaml 后,下次启动会重新生成一份全新配置
配置加载与校验逻辑可参考 src/stacks/config/config.py 和 src/stacks/config/validate.py。
二、完整默认配置参考
以下是一份典型的 config.yaml 默认内容,可作为对照基准:
server:
host: "0.0.0.0"
port: 7788
login:
username: admin
password: <bcrypt hash>
disable: false
api:
key: <32位密钥>
downloader_key: null
session_secret: <32位密钥>
downloads:
delay: 2
retry_count: 3
resume_attempts: 3
prefer_title_naming: false
include_hash: none
incomplete_folder_path: /download/incomplete
subdirectories: null
fast_download:
enabled: false
key: null
flaresolverr:
enabled: false
url: null
timeout: 60
proxy:
enabled: false
url: null
username: null
password: null
queue:
max_history: 100
logging:
level: INFO
三、config.yaml 参数逐项速查
3.1 server:服务地址与端口
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
server.host |
IP / URL | 0.0.0.0 |
监听地址,0.0.0.0 表示允许局域网其他设备访问 |
server.port |
整数 | 7788 |
Web 界面与 API 端口(范围 0-65535) |
💡 局域网访问示例:http://192.168.1.100:7788。如果 7788 端口被占用,修改 docker-compose.yml 中 ports 的左侧值即可。
3.2 login:登录账号与安全开关
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
login.username |
字符串(≤64字符) | admin |
Web 界面登录用户名 |
login.password |
bcrypt 哈希 | stacks |
以哈希形式存储,不要在 Web 界面直接编辑,通过 Settings 修改 |
login.disable |
布尔 | false |
设为 true 后禁用全部安全要求(登录密码和 API Key 全部失效),仅限内网可信环境使用 ⚠️ |
安全机制补充(见 src/stacks/constants.py):连续 5 次登录失败会锁定 10 分钟。
3.3 api:三种密钥的区别
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
api.key |
32位密钥 | 首次启动自动生成 | Admin Key:完整访问所有 API 端点 |
api.downloader_key |
32位密钥 / null | null |
Downloader Key:权限受限,只能添加下载任务和查看子目录,适合分发给 Tampermonkey 脚本 |
api.session_secret |
32位密钥 | 首次启动自动生成 | Web 会话签名密钥,请勿泄露 |
🔑 两种 Key 均可在 Web 界面 Settings → Authentication 中一键重新生成;密钥校验逻辑位于 src/stacks/security/auth.py。API 使用方式详见 docs/api.md。
3.4 downloads:下载行为(最常用的一组)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
downloads.delay |
整数(0-300) | 2 |
两个下载任务之间的间隔秒数,防止触发限流 |
downloads.retry_count |
整数(0-10) | 3 |
单个任务失败后的重试次数 |
downloads.resume_attempts |
整数(0-10) | 3 |
断点续传的最大尝试次数 |
downloads.prefer_title_naming |
布尔 | false |
为 true 时优先用书籍标题命名文件,而非文件名 |
downloads.include_hash |
枚举 | none |
文件名是否附加文件哈希:none / prefix / suffix,用于防止重名覆盖 |
downloads.incomplete_folder_path |
路径(≤128字符) | /download/incomplete |
未下载完成文件的临时目录。⚠️ 不能设为保留路径(/logs、/config、/files、/cache、/web,见 constants.py) |
downloads.subdirectories |
列表 | null |
允许的下载子目录白名单,Tampermonkey 脚本可从中选择目标目录 |
💡 修改 incomplete_folder_path 时,Stacks 会自动把旧目录中的未完成文件迁移到新位置(见 src/stacks/api/config.py),无需手动搬运。
3.5 fast_download:会员高速下载
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
fast_download.enabled |
布尔 | false |
开启后优先使用 Anna's Archive 会员快速下载 API |
fast_download.key |
字符串(≤256字符) | null |
会员账号的 secret key,在 Anna's Archive 账户设置中获取 |
⚡ 没有会员 Key 也不用慌:Stacks 会自动回退到镜像站慢速下载。启用后仪表盘还会显示剩余下载次数额度。
3.6 flaresolverr:绕过 Cloudflare 防护
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
flaresolverr.enabled |
布尔 | false |
是否启用 FlareSolverr 服务 |
flaresolverr.url |
IP / URL | 由 SOLVERR_URL 环境变量注入 |
你的 FlareSolverr 实例地址,如 http://flaresolverr:8191 |
flaresolverr.timeout |
整数(10-600) | 60 |
等待 FlareSolverr 返回结果的超时秒数 |
📌 遇到 403 错误基本就是镜像站的防护挡住了下载,启用 FlareSolverr 后可解决;Cookie 会按域名缓存 24 小时以节省调用。
3.7 proxy:全局代理
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
proxy.enabled |
布尔 | false |
是否启用代理 |
proxy.url |
URL | null |
代理地址,支持 http://、https://、socks5:// |
proxy.username |
字符串 | null |
代理认证用户名(可选) |
proxy.password |
字符串 | null |
代理认证密码(可选) |
代理配置会被下载器和爬虫进程同时读取(见 src/stacks/coordinator/download_worker.py),Web 界面还提供"Test Proxy"一键连通性测试。
3.8 queue 与 logging:队列历史和日志
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
queue.max_history |
整数(0-100000) | 100 |
保留的下载历史条数上限 |
logging.level |
枚举 | INFO |
日志级别:DEBUG / INFO / WARN / ERROR,排错时建议调成 DEBUG |
四、docker-compose.yml 环境变量全清单
环境变量主要在 docker-compose.yml 的 environment 中设置,完整说明见 docs/configuration.md。
| 变量 | 默认值 | 作用时机 | 说明 |
|---|---|---|---|
TZ |
UTC |
始终生效 | 日志与时间戳的时区 |
USERNAME |
admin |
仅首次运行 | 初始管理员用户名 |
PASSWORD |
stacks |
仅首次运行 | 初始管理员密码,务必修改 |
SOLVERR_URL |
— | 仅首次运行 | 首次运行时自动写入 flaresolverr.url |
RESET_ADMIN |
— | 设置后生效 | true 时强制把密码重置为 PASSWORD 变量的值,救急利器 |
FLASK_DEBUG |
— | 始终生效 | true 开启 Flask 调试模式(开发用) |
STACKS_PROJECT_ROOT |
自动推断 | 始终生效 | 覆盖项目根目录(PEX 部署场景使用,见 constants.py) |
⚠️ 最常见的困惑:USERNAME 和 PASSWORD 只在首次生成配置时生效。一旦 config.yaml 存在,这两个变量就会被忽略——之后想改账号请走 Web 界面,或临时设置 RESET_ADMIN=true 重启容器重置密码。
五、新手配置避坑指南
- 改密码别改文件:
login.password存的是 bcrypt 哈希,手动改哈希没有意义,请在 Settings 标签页修改 - API Key 只有 32 位:格式固定为 32 位字母数字,手写或改错一位都会被判定非法并回退
- 路径不能乱填:
incomplete_folder_path会被规范化为/path/to/folder形式,且禁止使用/logs、/config等保留路径 - 改文件要重启,改界面立即生效:两种方式的生效时机不同,排错时先确认你改的是哪一份
- 忘记密码有救:在 compose 文件加
RESET_ADMIN=true和新PASSWORD,重启后登录再移除该变量 - 安全提醒:不要把 Stacks 直接暴露公网;如需对外访问,配合 VPN 或带 HTTPS 的反向代理
六、相关源码与文档速查
- 配置模式定义(类型/默认值/范围):files/config_schema.yaml
- 配置加载与自动修复:src/stacks/config/config.py
- 校验与默认值回退规则:src/stacks/config/validate.py
- 配置读写 API(含路径迁移逻辑):src/stacks/api/config.py
- API Key 权限说明:src/stacks/api/keys.py
- 官方配置文档:docs/configuration.md
掌握以上参数与环境变量后,你已能自由定制 Stacks 的下载节奏、安全策略和外部服务集成。建议从默认的 delay: 2 + 3 次重试起步,跑顺之后再按网络环境微调即可。