VOMS 文档

Appearance

部署手册 ​

本文档说明基于 voms-deploy 的自部署流程。

部署基线 ​

当前生产部署基线（Web 向导方案）：

  • 部署程序：voms-deploy（deploy/）
  • 后端配置：/opt/voms/configs/config.production.json
  • 后端服务：voms-server、voms-worker-consumer、voms-worker-scheduler
  • 前端静态目录：/var/www/voms/admin 与 /var/www/voms/public
  • Caddy 站点配置：/etc/caddy/Caddyfile

环境要求 ​

  • Linux 主机（建议 Ubuntu 22.04+）
  • root/sudo 权限（安装系统服务需要）
  • 建议资源：4C8G 起步

发布包目录结构 ​

voms-deploy 所在目录应至少包含：

  • voms-deploy
  • bin/server
  • bin/worker-consumer
  • bin/worker-scheduler
  • frontend/admin/（后台前端静态文件）
  • frontend/public/（公众前端静态文件）
  • migrations/up/*.sql
  • configs/casbin/model.conf

发布包生成 ​

推荐在仓库根目录执行：

bash
# 自动使用当天日期作为版本号，例如 v20260220
make package-release

# 或指定版本号
make package-release VERSION=v20260220

产物目录：

  • dist/release/voms-release-<version>-linux-<arch>/
  • 对应 zip：dist/release/voms-release_<version>_linux_<arch>.zip

一键部署 ​

以 /opt/voms-release 为例：

bash
cd /opt/voms-release
sudo ./voms-deploy

运行后，程序会在终端打印浏览器访问地址，通过浏览器完成 Web 向导：

  1. 环境检测（自动）
  2. 依赖安装（选择并安装 PostgreSQL/Valkey/NATS/Caddy）
  3. 参数配置（DB、JWT、管理员账号、前端地址、端口）+ 连接测试
  4. 确认部署
  5. 自动部署进度（复制二进制、迁移、生成 config.production.json、生成 systemd、生成 Caddy）
  6. 健康检查 + 凭据显示

WARNING

如果已部署过，需要加 --force flag 重新执行：sudo ./voms-deploy --force

关键结果 ​

部署完成后会自动生成并启用：

  • /opt/voms/configs/config.production.json
  • /etc/systemd/system/voms-server.service
  • /etc/systemd/system/voms-worker-consumer.service
  • /etc/systemd/system/voms-worker-scheduler.service
  • /var/www/voms/admin
  • /var/www/voms/public
  • /etc/caddy/Caddyfile

健康检查 ​

bash
curl -s http://localhost:8181/api/v1/public/system/health | jq .
systemctl status voms-server --no-pager
systemctl status voms-worker-consumer --no-pager
systemctl status voms-worker-scheduler --no-pager

常用运维命令 ​

bash
# 查看后端日志
journalctl -u voms-server -f

# 查看 worker 日志
journalctl -u voms-worker-consumer -f
journalctl -u voms-worker-scheduler -f

# 重启服务
systemctl restart voms-server voms-worker-consumer voms-worker-scheduler

# 查看 Caddy 配置有效性并重载
caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy

升级与回滚 ​

方式一：OTA 自动更新（推荐） ​

VOMS 集成了 BanyanHub OTA 自动更新能力。管理员在 BanyanHub Dashboard 发布新版本后，运行中的服务会自动完成更新，无需登录服务器。详见 OTA 自动更新。

OTA 更新时旧版本会自动备份为 .bak 文件，可快速回滚：

bash
# 停止 → 恢复备份 → 启动
sudo systemctl stop voms-server
sudo cp /opt/voms/bin/server.bak /opt/voms/bin/server
sudo systemctl start voms-server

方式二：发布包重新部署 ​

替换发布包目录内容后重新执行部署向导：

bash
cd /opt/voms-release
sudo ./voms-deploy --force

方式三：回滚到旧版本 ​

切回旧发布包目录并再次执行：

bash
cd /opt/voms-release-prev
sudo ./voms-deploy --force

向导会重新覆盖二进制、配置和 systemd 单元，适合标准化重放部署。

说明 ​

  • voms-deploy 不依赖仓库内 .env/backend.env 文件。
  • 如需临时覆盖配置，优先修改 /opt/voms/configs/config.production.json 并重启对应服务。
  • 部署完成后会在发布包目录生成 .deploy.lock 锁文件，记录上次部署状态。
  • 使用 --force flag 可跳过锁文件检查，强制重新部署。

VOMS - 志愿者组织管理系统