瓦力 walle 配置参数详解
walle 2.0.1 四层配置全解：walle.env 环境变量、settings.py 应用参数、项目字段（审核/钩子/通知/路径陷阱）与 Nginx 接入层，含安全配置清单。
瓦力 walle 配置参数详解
walle 2.0.1 的配置分为四层：Compose 环境变量、应用配置文件、项目级配置（界面/数据库）与 Web 接入层。本文逐层逐项解析，全部取值基于官方 alenx/walle-python:2.1 镜像实测（实测日期 2026-10-25），并给出每项的修改方法与生效方式。
一、配置分层总览
| 层级 | 载体 | 典型内容 | 生效方式 |
|---|---|---|---|
| 部署变量 | walle.env / db.env（Compose env_file 注入） | 数据库连接、会话密钥 | 服务启动时读取，改动需重启后端服务 |
| 应用配置 | /opt/walle_home/walle/config/settings.py、settings_prod.py | 会话时效、邮箱、日志轮转 | 修改文件后重启后端服务 |
| 项目配置 | 界面「项目管理」→ projects 表字段 | 仓库、路径、审核、钩子、通知 | 保存即生效 |
| Web 接入层 | web 服务 Nginx 配置 | 对外端口、域名、WebSocket 反代 | 改配置后重载 Nginx |
层与层的关系：walle.env 提供数据库连接与密钥 → 应用配置消费它们并补充邮箱/日志等 → 项目配置决定每个项目「怎么发布」 → Nginx 决定「从哪访问」。
二、部署变量（walle.env / db.env）
walle 后端通过 environs 库读取以下环境变量（镜像版 walle/config/settings.py 实测）：
| 变量 | 必填 | 示例值 | 说明 |
|---|---|---|---|
MYSQL_HOST | 是 | db | MySQL 主机名。Compose 编排内为 db 服务名；裸机部署本地库填 127.0.0.1 |
MYSQL_PORT | 是 | 3306 | MySQL 端口 |
MYSQL_USER | 是 | root | walle 连库用户 |
MYSQL_PASSWORD | 是 | walle | 上述用户口令，生产必须修改 |
MYSQL_DATABASE | 是 | walle | 库名，需与 db 服务初始化的库名一致 |
MYSQL_ROOT_PASSWORD | 是 | walle | 仅 MySQL 服务（db）初始化 root 口令使用，放 db.env |
WALLE_SECRET | 否 | 任意长随机串 | Flask 会话签名密钥，缺省值 secret-key（settings.py 源码），生产必须显式设置 |
注意事项：
walle.env中的连接五元组必须与db.env初始化出的实例匹配（口令一致），否则迁移阶段即报Can't connect to MySQL server；- 官方 git 仓库 master 分支的
settings_prod.py仍是硬编码SETTINGS字典的旧写法，而官方镜像已改为读环境变量——以镜像实际行为为准； - 数据库连接串由
settings_prod.py按mysql://user:password@host:port/db?charset=utf8mb4拼装，字符集固定 utf8mb4。
三、应用配置（settings.py / settings_prod.py）
文件路径：后端安装目录 walle/config/ 下。关键字段（镜像实测值）：
| 参数 | 默认值 | 说明 |
|---|---|---|
VERSION | 2.0.1 | 版本号 |
SECRET_KEY | 环境变量 WALLE_SECRET，缺省 secret-key | 会话与令牌签名密钥 |
PERMANENT_SESSION_LIFETIME | 1 天（timedelta） | 登录会话有效期 |
BCRYPT_LOG_ROUNDS | 13 | 口令哈希强度 |
WTF_CSRF_ENABLED | False | CSRF 关闭（内网工具定位；若暴露半公网建议评估开启的兼容性） |
CACHE_TYPE | simple | 进程内缓存，单机部署无需调整 |
MAIL_SERVER | smtp.exmail.qq.com | 邮件通知 SMTP 服务器 |
MAIL_PORT / MAIL_USE_SSL | 465 / True | SMTP 端口与 SSL |
MAIL_USERNAME / MAIL_PASSWORD | 项目作者的示例邮箱 | 接入邮件通知前必须替换（源码内置凭据，公开仓库可见） |
MAIL_DEFAULT_SENDER | 同上 | 默认发件人 |
LOG_PATH | <安装目录>/logs | 日志目录（Compose 中挂载到宿主机 data/logs） |
LOG_PATH_ERROR / LOG_PATH_INFO | error.log / info.log | 错误与信息日志文件 |
LOG_FILE_MAX_BYTES | 100 MB | 单日志文件上限 |
LOG_FILE_BACKUP_COUNT | 10 | 轮转保留个数 |
COOKIE_ENABLE | False | 「记住登录」Cookie 开关 |
HOST / PORT | 0.0.0.0 / 5000 | 后端监听地址（settings_prod.py），与 Nginx 反代目标一致 |
SSL | False | 后端直连 HTTPS 开关，一般由 Nginx 终结 TLS，保持 False |
CODE_BASE | /tmp/walle/codebase/ | 代码检出与打包目录（settings_prod.py），Compose 挂载点 |
改法示例：接入自有邮箱通知，编辑 settings.py（或 settings_prod.py）覆盖 MAIL_* 五项后重启后端服务。
四、项目级配置（projects 字段全解）
创建/编辑项目时的完整字段与实测语义：
| 字段 | 界面位置 | 说明 |
|---|---|---|
name | 项目名称 | 项目标识，空间内唯一 |
environment_id | 环境 | 所属环境（测试/生产），一个项目只属一个环境 |
status | 启用状态 | 1=启用（status_open）、0=停用（status_close），停用项目不出现在发布入口 |
space_id | —（由当前空间决定） | 项目归属的空间 |
repo_url | 仓库地址 | git 协议支持 http(s)/git/ssh；walle 主机必须可达该地址 |
repo_mode | 仓库模式 | branch（按分支选 commit）或 tag（按标签），上线单入口随之变化 |
target_root | 目标路径 | 目标机上对外服务的路径，walle 将其管理为软链接，首次发布前不要预建实体目录 |
target_releases | 版本库路径 | 历史版本目录（1_上线单ID_时间戳 命名），必须与 target_root 不同路径 |
is_include + excludes | 排除/仅包含文件 | 是否启用文件过滤（0 不启用）及规则列表，控制分发内容 |
master | 负责人 | 项目主管的用户 ID 列表（逗号分隔），展示与检索用途 |
server_ids | 目标服务器 | 参与发布的服务器清单（多选） |
keep_version_num | 保留版本数 | 发布后目标机保留的历史版本数（实测发布链按 tail -n +N 清理旧版本） |
task_audit | 上线审核 | 1 开启：上线单需审核通过才出现「上线」按钮；0 关闭直接可发布 |
prev_deploy / post_deploy | 部署前/后钩子 | 在 walle 主机代码检出阶段前后执行的自定义脚本 |
prev_release / post_release | 切换前/后钩子 | 在目标机版本切换阶段前后执行的自定义脚本（如重启进程、清理缓存） |
task_vars | 自定义变量 | 发布过程中可引用的变量定义 |
notice_type | 通知方式 | dingding（钉钉机器人）或 email（邮件，需第三节 SMTP 可用） |
notice_hook | 通知地址 | 钉钉机器人的 webhook 地址 |
配置陷阱（实测复现）：target_root 与 target_releases 配成同一路径会让软链管理逻辑自毁目录；二者必须分置（如 /srv/www/demo-web 与 /srv/www/demo-releases）。
五、上线单字段
| 字段 | 说明 |
|---|---|
name | 上线单标题，建议带变更说明 |
project_id | 所属项目 |
servers | 本次发布生效的服务器（默认全选项目服务器，可裁剪实现按机灰度） |
branch | 发布分支（repo_mode=branch 时） |
commit_id | 发布的具体 commit——必选，实测缺省时部署阶段 git reset --hard 失败 |
上线单状态机（实测）：创建 → （task_audit=1 时）等待审核 → 上线执行 → 成功/失败；每次上线/回滚都在上线单列表留痕，回滚会生成一条 is_rollback=1 的新上线单并重新指向上一版本目录。
六、Web 接入层（Nginx 与域名）
web 服务的 Nginx 配置（镜像内置）要点：
- 前端静态资源根目录
/data/walle（Vue 构建产物），未匹配路径回落index.html； /api/反代到后端python:5000，并传递X-Forwarded-Host（供通知消息里的链接使用）；/socket.io/反代同一后端，带 WebSocket 升级头（Upgrade/Connection "upgrade"、proxy_http_version 1.1）——实时日志依赖此段，自建反代（如外层再套一层网关）时必须同样透传升级头。
对外端口在 Compose 的 ports 中映射（本文部署指南示例为 8134:80，生产可改 80:80 或配合自有域名/证书网关使用）。使用域名访问时，通知消息中的回跳链接取自 X-Forwarded-Host，因此外层网关需正确传递 Host 信息。
七、权限与通知的联动配置
- 审核流：项目
task_audit=1后，普通成员提交的上线单进入待审核状态；具备审核权限的角色（如项目负责人/空间管理员）在上线单列表中执行「审核」，通过后方可上线。建议生产环境项目统一开启； - 钉钉通知：
notice_type=dingding且notice_hook填入群机器人 webhook；发布成功/失败消息会携带项目、上线单与结果摘要； - 邮件通知：
notice_type=email，依赖第三节MAIL_*配置；默认内置的是项目作者示例邮箱，必须替换。
八、安全配置清单
| 项 | 缺省 | 建议 |
|---|---|---|
| 超管账号 | super@walle-web.io / Walle123 | 部署后立即改密 |
WALLE_SECRET | secret-key | 设置 32+ 位随机串 |
| MySQL 口令 | walle | 修改 walle.env 与 db.env 并保持一致 |
| 内置 SMTP 凭据 | 源码硬编码示例邮箱 | 替换为自有 SMTP 账号 |
| CSRF | 关闭 | 保持内网使用，勿直接暴露公网 |
| 目标机 SSH | 部署公钥免密 | 独立密钥对 + 最小权限用户 |
配置项的部署落地步骤见《walle v2.0.1 Docker Compose 部署指南》，服务管理与升级命令见《walle v2.0.1 常用 CLI 命令详解》。