VOMS 文档

Appearance

故障排查 ​

默认工作目录：/opt/voms。

一键体检 ​

bash
systemctl status voms-server --no-pager
systemctl status voms-worker-consumer --no-pager
systemctl status voms-worker-scheduler --no-pager
systemctl status postgresql --no-pager
systemctl status redis --no-pager
systemctl status nats --no-pager

curl -s http://localhost:8181/api/v1/public/system/health | jq .
curl -s http://localhost:8222/healthz

常见问题 ​

voms-server 启动失败 ​

bash
journalctl -u voms-server -n 200 --no-pager

重点关注：

  • config.production.json 语法错误
  • 数据库/Redis/NATS 连接失败
  • JWT、超级管理员等关键配置缺失

前端可访问但 API 全部报错 ​

排查：

bash
curl -s http://localhost:8181/api/v1/public/system/health | jq .
caddy validate --config /etc/caddy/Caddyfile
journalctl -u caddy -n 200 --no-pager

常见原因：

  • Caddy 反代地址错误
  • 后端端口与配置不一致
  • 后端服务未启动或反复崩溃

登录失败（401/403） ​

排查：

  1. 查看后端鉴权日志：
bash
journalctl -u voms-server -n 200 --no-pager
  1. 检查系统时间同步（NTP）
  2. 核对配置中的 JWT 配置：/opt/voms/configs/config.production.json

Worker 不消费消息 ​

bash
systemctl status voms-worker-consumer --no-pager
systemctl status voms-worker-scheduler --no-pager
journalctl -u voms-worker-consumer -n 200 --no-pager
journalctl -u voms-worker-scheduler -n 200 --no-pager
curl -s http://localhost:8222/jsz | jq .

常见原因：

  • NATS 不可达
  • Worker 与 Server 配置不一致

数据库迁移相关错误 ​

bash
journalctl -u voms-server -n 200 --no-pager

必要时检查迁移记录（示例）：

bash
sudo -u postgres psql -d voms_production -c "SELECT id,name,applied_at FROM voms_schema_migrations ORDER BY id;"

Redis 连接失败 ​

bash
redis-cli ping
journalctl -u redis -n 200 --no-pager

问题分级 ​

  • P1：系统不可用（登录/核心业务中断）
  • P2：部分功能不可用（导入、通知等）
  • P3：体验问题或可降级问题

建议流程：

  1. 先恢复可用性（重启异常服务或回滚发布包）
  2. 再保留证据（日志、时间线、配置快照）
  3. 最后修复根因并补充回归测试

紧急回滚 ​

OTA 回滚（推荐） ​

OTA 更新时自动备份旧版本为 .bak 文件：

bash
# 1. 停止服务
sudo systemctl stop voms-server

# 2. 恢复备份
sudo cp /opt/voms/bin/server.bak /opt/voms/bin/server

# 3. 重启服务
sudo systemctl start voms-server

# 4. 验证
curl -s http://localhost:8181/api/v1/public/system/health | jq .

发布包回滚 ​

bash
# 1) 切换到上一版发布目录
cd /opt/voms-release-prev

# 2) 重新执行部署
sudo ./voms-deploy

# 3) 复检
curl -s http://localhost:8181/api/v1/public/system/health | jq .

OTA 更新问题 ​

OTA 更新未触发 ​

bash
# 检查心跳日志
journalctl -u voms-server --no-pager -n 100 | grep -i heartbeat

# 检查是否有更新相关日志
journalctl -u voms-server --no-pager -n 100 | grep -i -E "update|ota"

常见原因：

  • 许可证状态异常（过期、暂停）
  • 网络无法访问 BanyanHub API (guard.iluwen.cn)
  • BanyanHub 上没有发布新版本或未标记为"最新"

OTA 下载失败 ​

bash
journalctl -u voms-server --no-pager -n 200 | grep -i -E "download|artifact|error"

常见原因：

  • 网络不稳定，大文件下载超时
  • R2 存储桶中制品不存在
  • 制品 SHA256 或签名校验失败

SDK 会在下次心跳时自动重试下载。

OTA 更新后服务未重启 ​

bash
# 检查 systemd 配置
systemctl show voms-server | grep -E "Restart=|RestartSec="

确保 Restart=always（非 on-failure），否则 OTA 的优雅退出（SIGTERM）不会触发重启：

bash
sudo sed -i 's/Restart=on-failure/Restart=always/' /etc/systemd/system/voms-server.service
sudo systemctl daemon-reload
sudo systemctl restart voms-server

VOMS - 志愿者组织管理系统