Wallos 5.10.2 配置参数详解

目标：把 Wallos v5.10.2 的全部配置参数讲清楚——用户级显示偏好（settings 表）、实例级管理参数（admin 表）、环境变量声明式配置（WALLOS_* / OIDC_* / SSRF_ALLOWLIST / DEMO_MODE / TZ）、多币种、通知渠道与 AI 推荐参数，逐项给出含义、默认值与实测回显，并给出生产配置模板。已在 Ubuntu 22.04.5 LTS + Wallos 5.10.2（SQLite 后端）实测通过（2026-10-25）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（裸机部署形态；容器形态参数完全通用）
• 系统架构：x86_64
• Wallos 版本：v5.10.2
• 数据库：SQLite 3.37.2，单文件 /var/www/html/db/wallos.db
• 配置载体：settings 表（用户级）、admin 表（实例级）、环境变量（部署级）
• 演示账号：admin / q1w2e3r4（user_id=1）
• 部署方式参考：《Ubuntu 22.04 安装 Wallos 5.10.2 指南》 或 《Wallos 5.10.2 Docker Compose 部署指南》

二、前置条件

• 已完成 Wallos 5.10.2 部署并注册首个账号（本文所有示例基于该实测环境）。
• 需要用命令行查看/核对参数时，服务器上安装 sqlite3：

sudo apt-get install -y sqlite3
sqlite3 --version

输出（实测）：

3.37.2 2022-01-06 13:25:41 872ba256cbf61d9290b571c0e6d82a20c224ca3ad82971edc46b29818d5dalt1

⚠️ 注意：直接改库前建议先备份：cp /var/www/html/db/wallos.db /var/www/html/db/wallos.db.bak。Web 界面能改的参数优先走 Web 界面，直改 SQL 仅用于排障与批量核对。

三、参数查看与修改方式

Wallos 的参数分三层载体，各有对应的查看与修改入口。本节先把三条路径都跑通，后续章节逐项详解。

3.1 方式一：Web 界面（推荐）

• 用户级显示偏好：登录后右上角头像 → Settings（设置页），对应 settings 表。
• 实例级参数：管理员登录后进入 Admin（管理页），对应 admin 表。
• 字典类参数：设置页内的分类 / 支付方式 / 家庭成员 / 币种汇率等卡片，对应各自的业务表。

3.2 方式二：sqlite3 直查直改（排障/核对用）

查看 settings 表结构（实测）：

sqlite3 /var/www/html/db/wallos.db "PRAGMA table_info(settings);"

输出（实测）：

0|dark_theme|BOOLEAN|0|0|0
1|monthly_price|BOOLEAN|0|0|0
2|convert_currency|BOOLEAN|0|0|0
3|remove_background|BOOLEAN|0|0|0
4|color_theme|TEXT|0|'blue'|0
5|hide_disabled|BOOLEAN|0|0|0
6|user_id|INTEGER|0|1|0
7|disabled_to_bottom|BOOLEAN|0|0|0
8|show_original_price|BOOLEAN|0|0|0
9|mobile_nav|BOOLEAN|0|0|0
10|show_subscription_progress|BOOLEAN|0|0|0
11|week_starts_sunday|BOOLEAN|0|0|0
12|upcoming_payments_limit|INTEGER|0|3|0

直改示例（把用户 1 切到深色主题，并立即查回验证，实测）：

sqlite3 /var/www/html/db/wallos.db "UPDATE settings SET dark_theme=1 WHERE user_id=1;"
sqlite3 /var/www/html/db/wallos.db "SELECT dark_theme,color_theme,upcoming_payments_limit FROM settings WHERE user_id=1;"

输出（实测）：

1|blue|3

dark_theme 已由 0 变为 1，刷新页面即生效（示例验证后已改回 0）。

3.3 方式三：环境变量声明式覆盖（部署级）

实例级的 SMTP 与对外 URL 可以被环境变量整体接管，机制由 includes/instance_config.php 实现。实测验证（设置变量后读取到的实例配置被环境变量覆盖）：

cd /var/www/html
WALLOS_SMTP_HOST=smtp.example.com WALLOS_SMTP_PORT=465 WALLOS_SMTP_ENCRYPTION=ssl WALLOS_SERVER_URL=https://wallos.example.com php -r "
require \"includes/instance_config.php\";
\$db = new SQLite3(\"db/wallos.db\");
\$r = wallos_get_effective_admin_configuration(\$db);
foreach (\$r[\"settings\"] as \$k=>\$v) { if (in_array(\$k,[\"smtp_address\",\"smtp_port\",\"encryption\",\"server_url\"])) echo \$k.\"=\".\$v.PHP_EOL; }
echo \"managed: \".implode(\",\", array_map(function(\$k,\$v){return \$k.\"<=\".\$v;}, array_keys(\$r[\"managed_fields\"]), \$r[\"managed_fields\"])).PHP_EOL;
"

输出（实测）：

server_url=https://wallos.example.com
smtp_address=smtp.example.com
smtp_port=465
encryption=ssl
managed: smtp_address<=WALLOS_SMTP_HOST,smtp_port<=WALLOS_SMTP_PORT,encryption<=WALLOS_SMTP_ENCRYPTION,server_url<=WALLOS_SERVER_URL

被接管的字段在 Admin 管理页显示为只读（页面会标注该字段由环境变量管理），防止「环境变量一份、数据库一份」不一致。完整变量清单见"五、核心参数分类详解 → 5.3"。

四、参数总览

Wallos v5.10.2 数据库共 40 张表（实测 .tables），与「配置参数」直接相关的可归为 6 组：

关键差异解读：改「界面长什么样」找 settings，改「这个实例怎么运转」找 admin，改「部署基础设施」（SMTP、对外 URL、OIDC）用环境变量；环境变量一旦设置即覆盖 admin 表同名配置。

五、核心参数分类详解

5.1 用户级显示偏好（settings 表）

每个注册用户一行，全部为界面展示与交互偏好，实测默认行如下：

sqlite3 /var/www/html/db/wallos.db "SELECT * FROM settings;"

输出（实测，字段顺序同 PRAGMA）：

0|0|0|0|blue|0|1|0|0|0|0|0|3

逐项说明（按 PRAGMA 字段序）：

5.2 实例级管理参数（admin 表）

全实例仅一行，由管理员在 Admin 页维护。表结构（实测）：

sqlite3 /var/www/html/db/wallos.db "PRAGMA table_info(admin);"

输出（实测）：

0|id|INTEGER|0||1
1|registrations_open|BOOLEAN|0|0|0
2|max_users|INTEGER|0|0|0
3|require_email_verification|BOOLEAN|0|0|0
4|server_url|TEXT|0||0
5|smtp_address|TEXT|0||0
6|smtp_port|INTEGER|0|587|0
7|smtp_username|TEXT|0||0
8|smtp_password|TEXT|0||0
9|from_email|TEXT|0||0
10|encryption|TEXT|0|'tls'|0
11|login_disabled|BOOLEAN|0|0|0
12|latest_version|TEXT|0|'v2.21.1'|0
13|update_notification|BOOLEAN|0|0|0
14|oidc_oauth_enabled|INTEGER|0|0|0
15|local_webhook_notifications_allowlist|TEXT|0|''|0
16|allow_standard_users_local_webhooks|INTEGER|0|0|0
17|vapid_public_key|TEXT|0|''|0
18|vapid_private_key|TEXT|0|''|0

当前实例实测行（关键列）：

1|0|0|0|||587|tls|0|0|v5.10.2|0

（列序：id、registrations_open、max_users、require_email_verification、server_url、smtp_address、smtp_port、encryption、login_disabled、oidc_oauth_enabled、latest_version、update_notification。）

逐项说明：

⚠️ 注意：server_url、smtp_*、encryption、from_email 共 7 个字段可被环境变量接管（见 5.3）；接管后 Admin 页对应输入框变为只读，改库无效（读取时环境变量优先）。

5.3 环境变量声明式配置（WALLOS_* / OIDC_* / SSRF_ALLOWLIST / DEMO_MODE / TZ）

*1. WALLOS_ 实例配置变量（7 项）**，与 admin 表字段一一对应：

取值优先级（源码 wallos_env_secret() 实现，实测于 5.10.2）：<变量名>_FILE 文件内容 > 环境变量值 > admin 表存储值。空字符串变量视为未配置（会被忽略并在日志记 note），避免笔误把邮件通道静默关掉。

裸机部署注入方式（php-fpm 需在池配置或 systemd 中传递环境变量）：

# /etc/php/8.3/fpm/pool.d/www.conf 中追加（每个变量一行）
env[WALLOS_SMTP_HOST] = smtp.example.com
env[WALLOS_SMTP_PORT] = 465
env[WALLOS_SMTP_ENCRYPTION] = ssl
env[WALLOS_SMTP_USERNAME] = wallos@example.com
env[WALLOS_SMTP_FROM] = wallos@example.com
env[WALLOS_SERVER_URL] = https://wallos.example.com

sudo systemctl restart php8.3-fpm

容器部署直接在 compose environment: 段声明即可（见 《Wallos 5.10.2 Docker Compose 部署指南》第六章）。

*2. OIDC_ 单点登录变量（16 项）**，用于声明式配置 OIDC/OAuth：

3. 其余部署级变量：

5.4 多币种与汇率参数

币种字典在 currencies 表，v5.10.2 预置 33 个币种（实测）：

sqlite3 /var/www/html/db/wallos.db "SELECT COUNT(*) FROM currencies;"
sqlite3 /var/www/html/db/wallos.db "SELECT id,name,symbol,code FROM currencies LIMIT 8;"
sqlite3 /var/www/html/db/wallos.db "SELECT id,name,symbol,code FROM currencies WHERE code='CNY';"

输出（实测）：

33
1|Euro|€|EUR
2|US Dollar|$|USD
3|Japanese Yen|¥|JPY
4|Bulgarian Lev|лв|BGN
5|Czech Republic Koruna|Kč|CZK
6|Danish Krone|kr|DKK
7|British Pound Sterling|£|GBP
8|Hungarian Forint|Ft|HUF
21|Chinese Yuan|¥|CNY

相关参数：

• user.main_currency：每个用户的主币种（折算目标），实测 admin 用户为 21（CNY）：SELECT id,username,email,main_currency FROM user; → 1|admin|admin@example.com|21。在设置页修改。
• Fixer API Key：汇率数据源，存于 fixer 表；在设置页填入 fixer.io 的 API Key 后，updateexchange.php 定时任务才会真正拉取汇率，否则日志显示 Exchange rates update skipped. No fixer.io api key provided。
• 显示层开关 convert_currency、show_original_price 见 5.1。

5.5 通知渠道参数

Wallos 每个通知渠道一张表（用户级，实测 .tables 输出）：

关键参数共性：每张渠道表都含启用开关、渠道地址/凭据、以及「提前几天通知」等触发字段；在设置页按渠道卡片填写，保存后由 sendnotifications.php（每天 09:00）与 sendcancellationnotifications.php（每天 08:00）定时任务消费。私有地址的 Webhook（如内网 Gotify）需要在 admin 表 local_webhook_notifications_allowlist 或环境变量 SSRF_ALLOWLIST 中放行。

5.6 AI 推荐参数（ai_settings 表）

AI 订阅建议功能的参数存于 ai_settings 表（每用户每类型一行），结构实测：

0|id|INTEGER|0||1
1|user_id|INTEGER|1||0
2|type|TEXT|1||0
3|enabled|BOOLEAN|1|0|0
4|api_key|TEXT|0||0
5|model|TEXT|1||0
6|url|TEXT|0||0
7|run_schedule|TEXT|1|'manual'|0
8|last_successful_run|DATETIME|0||0
9|created_at|DATETIME|0|CURRENT_TIMESTAMP|0
10|updated_at|DATETIME|0|CURRENT_TIMESTAMP|0

逐项说明：type 为 AI 提供方（ChatGPT / Gemini / Ollama）；api_key 为对应平台密钥；url 仅本地 Ollama 需要（服务地址）；run_schedule 为生成节奏（manual 手动 / weekly / monthly，由 generaterecommendations.php 定时任务驱动）。api_key 属敏感值，仅在设置页填写，不要写入任何文档或脚本。

5.7 OIDC 单点登录参数（oauth_settings 表 + 环境变量）

管理页配置 OIDC 时参数存于 oauth_settings 表，结构实测（节选关键字段）：client_id、client_secret、authorization_url、token_url、user_info_url、redirect_url、logout_url、user_identifier_field（默认 'sub'）、scopes（默认 'openid email profile'）、auth_style（默认 'auto'）、auto_create_user、password_login_disabled、require_email_verified（默认 1）。

同一组参数也可用 5.3 的 OIDC_* 环境变量整体声明；声明式方式更适合容器化部署与基础设施即代码管理。

六、生产配置模板

适用场景：个人/家庭单实例自托管，1–5 个用户，SQLite 后端，经反向代理以 HTTPS 对外。

1. 部署级环境变量（推荐全量声明，裸机写入 php-fpm 池配置，容器写入 compose）：

TZ=Asia/Shanghai
WALLOS_SERVER_URL=https://wallos.example.com
WALLOS_SMTP_HOST=smtp.example.com
WALLOS_SMTP_PORT=465
WALLOS_SMTP_ENCRYPTION=ssl
WALLOS_SMTP_USERNAME=wallos@example.com
WALLOS_SMTP_PASSWORD_FILE=/run/secrets/wallos_smtp_password
WALLOS_SMTP_FROM=wallos@example.com
SSRF_ALLOWLIST=gotify.lan:8080

2. Admin 管理页建议值：

3. 用户级设置建议：主币种选 CNY；开启「折算成主币种显示」+「显示原始价格」兼顾总账与明细；「即将付款条数」按订阅数量调到 5–10；通知渠道至少配一个（邮件或 Telegram/Gotify），提前 3 天提醒。

4. 汇率：到 fixer.io 申请免费 API Key 填入设置页，否则多币种折算不可用（免费 Key 有月度调用配额，Wallos 每天 02:00 拉一次足够）。

七、常见问题

7.1 改了 admin 表的 SMTP 字段为什么不生效？

该字段已被同名 WALLOS_* 环境变量接管（Admin 页对应输入框为只读）。取值优先级是 _FILE > 环境变量 > 数据库。要么改环境变量并重启 php-fpm/重建容器，要么 unset 变量把控制权还给数据库。确认哪些字段被接管可用 3.3 的实测脚本查看 managed_fields。

7.2 WALLOS_SMTP_ENCRYPTION 填了大写 SSL 可以吗？

可以，源码会先转小写再校验，仅接受 none / tls / ssl；填其他值会被忽略并保留库中原值（不会报错中断）。

7.3 私有地址的 Webhook（如内网 Gotify）不通知？

Wallos 默认拦截指向私有地址的回调（防 SSRF）。在 Admin 页安全设置填写放行清单，或用环境变量 SSRF_ALLOWLIST=gotify.lan:8080（多个用逗号分隔）；环境变量设置后整表覆盖管理页清单。

7.4 时区改了 TZ 为什么页面时间没变？

裸机部署时 TZ 需要注入到 php-fpm 进程环境（池配置 env[TZ] 或 systemd 单元），仅改 shell 的 /etc/environment 对 php-fpm 不生效；注入后 systemctl restart php8.3-fpm。Wallos 时区取值顺序：TZ 环境变量 → PHP 默认时区 → UTC。

7.5 多币种订阅总金额不对？

先确认：① 设置页已填 Fixer API Key；② 该用户主币种 main_currency 正确；③ convert_currency 已开启；④ 汇率任务已跑过（updateexchange.php，可手工执行一次验证，回显 Exchange rates update skipped 即表示 Key 未配置）。

八、参考链接

• 官方仓库（含环境变量完整表格）：https://github.com/ellite/Wallos
• 官方演示站：https://demo.wallosapp.com
• Fixer 汇率 API：https://fixer.io
• 本站相关文档：《Wallos 介绍与选型指南》、《Ubuntu 22.04 安装 Wallos 5.10.2 指南》、《Wallos 5.10.2 Docker Compose 部署指南》