Wallos 项目部署

一、功能概览

二、部署方案选择

三、环境要求

Docker 方案

• 已安装 Docker Engine 与 Docker Compose 插件
• 内存 256MB 以上即可，磁盘占用很小
• 默认映射端口：8282（容器内 80）

裸机方案

• Nginx 或 Apache 网页服务
• PHP 8.3（README 的较新版本写法；较早的 README 写的是 8.2，请以你所用版本为准），并启用以下模块：curl、dom、gd、imagick、intl、openssl、sqlite3、zip、mbstring，使用 Nginx 时还需 php-fpm
• 能写入 db 目录与 logos 目录

四、Docker Compose 部署（推荐）

4.1 创建目录

mkdir -p ~/wallos/{db,logos}
cd ~/wallos

4.2 编写 docker-compose.yml

services:
  wallos:
    container_name: wallos
    image: bellamy/wallos:latest
    ports:
      - "8282:80/tcp"
    environment:
      TZ: "Asia/Shanghai"
    volumes:
      - ./db:/var/www/html/db
      - ./logos:/var/www/html/images/uploads/logos
    restart: unless-stopped

说明：

• ./db 保存数据库，是最重要的数据目录，务必持久化。
• ./logos 保存上传的订阅 Logo。
• TZ 设置时区，直接影响提醒通知的发送时间，请设为你所在的时区。
• 如果 Docker 版本低于 25，或想让容器更快报告启动状态，官方提供了关闭健康检查的写法：在服务下增加 healthcheck: test: ["NONE"]。
• 生产环境建议把镜像标签固定到具体版本号，按需升级。
• 想通过反向代理对外提供服务，可把端口映射改为只监听本机（127.0.0.1:8282:80）。

4.3 启动

docker compose up -d
docker compose ps
docker compose logs -f wallos

4.4 Docker 单命令（替代方案）

docker run -d --name wallos \
  -v /path/to/config/wallos/db:/var/www/html/db \
  -v /path/to/config/wallos/logos:/var/www/html/images/uploads/logos \
  -e TZ=Asia/Shanghai \
  -p 8282:80 \
  --restart unless-stopped \
  bellamy/wallos:latest

五、首次使用

1. 浏览器访问「服务器IP地址:8282」。
2. 首次访问需要自己创建账号，没有默认账号密码，这点比许多同类工具更安全。
3. 进入设置：
   • 设置头像、添加家庭成员
   • 增删分类与币种，设置主货币
4. 开始添加订阅：填写名称、金额、币种、周期、下次付款日、分类与付款方式。
5. 到管理页面检查注册开关等选项。个人自用建议在建好账号后关闭开放注册，具体入口以界面为准。

六、汇率配置

Wallos 使用 Fixer 提供汇率数据，需要自己申请免费密钥：

1. 到 Fixer 服务注册并获取 API Key。
2. 在 Wallos 的设置里填入该密钥。
3. 如需立刻刷新汇率：先修改主货币，再改回你想要的主货币，这会触发一次汇率更新。
4. 免费套餐有请求次数限制，Wallos 默认每天定时更新一次，通常足够个人使用。

七、通知配置

在设置的通知页面启用你需要的渠道，并填写对应参数：

配置后先使用页面上的测试功能，确认能收到消息，再依赖它做续费提醒。

重要：内网地址的安全限制

新版 Wallos 为了防止服务端请求伪造（SSRF），会拦截解析到内网、本地回环或链路本地地址的 Webhook、SMTP 和 OIDC 地址，除非该主机已加入「安全设置」中的白名单。

这意味着：

• 如果你的 Gotify、自建邮件服务或身份提供商在内网，保存配置时可能被拒绝。
• 解决办法：到管理页面的安全设置中，把这些内网主机加入白名单，然后再保存通知配置。
• 如果通知渠道在公网，则不受此限制影响。

八、反向代理与 HTTPS

Caddy 示例：

sub.你的域名 {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8282
}

使用 Nginx 反向代理时，常规配置即可：转发请求头，并适当调大上传大小限制（上传 Logo 用）。

安全建议：

• 订阅清单与金额属于财务隐私，对外开放时务必使用 HTTPS 并设置强密码。
• 不需要外网访问就只在内网使用，或通过 VPN 访问。
• 启用 OIDC 单点登录时，建议同时关闭不必要的本地注册。

九、OIDC 单点登录（可选）

在管理页面可启用 OIDC，适用于支持 OAuth 的身份提供商。基本步骤：

1. 在身份提供商处创建一个应用，回调地址填写 Wallos 的访问地址对应的回调路径（具体路径请对照 Wallos 管理页面的提示）。
2. 把客户端 ID、客户端密钥和发现地址等信息填入 Wallos 的 OIDC 设置。
3. 如果身份提供商在内网，需先在安全设置里加入白名单（见第七章）。
4. 配置后先用另一个浏览器测试登录，确认无误再关闭本地密码登录，避免把自己锁在外面。

README 没有给出 OIDC 的详细配置步骤，具体字段请以管理页面和官方文档为准。

十、裸机部署（可选）

1. 下载或克隆仓库，把文件放到网站根目录（通常是 /var/www/html）。
2. 把 db/wallos.empty.db 重命名为 db/wallos.db。
3. 执行数据库迁移：登录后在浏览器中访问迁移页面，或在命令行执行：

php /var/www/html/endpoints/db/migrate.php

4. 确保 db 与 images/uploads/logos 目录对网页服务用户可写。
5. 配置定时任务（crontab -e）。如果网站根目录不是 /var/www/html，请相应调整路径：

0 2 * * * php /var/www/html/endpoints/cronjobs/updateexchange.php >> /var/log/cron/updateexchange.log 2>&1
0 8 * * * php /var/www/html/endpoints/cronjobs/sendcancellationnotifications.php >> /var/log/cron/sendcancellationnotifications.log 2>&1
0 9 * * * php /var/www/html/endpoints/cronjobs/sendnotifications.php >> /var/log/cron/sendnotifications.log 2>&1
*/2 * * * * php /var/www/html/endpoints/cronjobs/sendverificationemails.php >> /var/log/cron/sendverificationemail.log 2>&1
*/2 * * * * php /var/www/html/endpoints/cronjobs/sendresetpasswordemails.php >> /var/log/cron/sendresetpasswordemails.log 2>&1
0 */6 * * * php /var/www/html/endpoints/cronjobs/checkforupdates.php >> /var/log/cron/checkforupdates.log 2>&1
30 1 * * 1 php /var/www/html/endpoints/cronjobs/storetotalyearlycost.php >> /var/log/cron/storetotalyearlycost.log 2>&1

各任务分别负责：更新汇率、发送取消提醒、发送续费通知、发送验证邮件与重置密码邮件、检查更新、统计年度总成本。没有这些定时任务，通知与汇率更新都不会工作。

Docker 镜像已经内置这些任务，使用 Docker 部署时无需手动配置。

十一、备份、升级与迁移

11.1 备份

cd ~/wallos
tar czf wallos-backup-$(date +%F).tar.gz db logos

• 数据库是单个 SQLite 文件，建议先停止容器再备份，保证文件一致。
• 数据包含你的订阅清单、金额和通知凭据（如 SMTP 密码、机器人令牌），备份文件要加密保存。
• 遵循 3-2-1 原则：3 份副本、2 种介质、1 份异地。

11.2 升级

Docker：

cd ~/wallos
docker compose pull
docker compose up -d
docker image prune

裸机：重新下载仓库覆盖文件，或在原目录执行 git pull，随后执行迁移脚本。

建议：

• 升级前先备份 db 目录，并查看发布说明。
• 固定镜像标签，避免意外升级。

11.3 迁移

在新机器部署相同方案，把 db 与 logos 目录复制过去，启动即可。

十二、常见问题排查

十三、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart wallos

# 查看日志
docker compose logs -f wallos

# 备份
tar czf wallos-backup-$(date +%F).tar.gz db logos

# 升级
docker compose pull && docker compose up -d

# 裸机：数据库迁移
php /var/www/html/endpoints/db/migrate.php