Operations

🛠️ 运行维护

运行维护需要同时检查服务身份、转换能力、依赖访问、资源使用和持久化状态。

日常检查

检查	方法	成功条件
进程健康	/healthz	返回 ok
版本身份	/version	显示预期版本和源代码修订
转换功能	使用公开测试输入执行 /sub	状态、正文和目标格式正确
日志	Docker、journald 或文件日志	无持续重启、OOM、配置加载或抓取错误
磁盘	检查配置、统计和容器日志目录	有足够空间，日志受到限制
外部依赖	外部配置、规则和需要后端解析的订阅	能按配置的出站策略访问

/healthz 不检查外部配置、规则、模板和真实转换，不能作为唯一监控信号。

Docker 常用命令

docker ps --filter name=SubConverter-Extended
docker logs --tail 100 SubConverter-Extended
docker restart SubConverter-Extended
docker inspect SubConverter-Extended

使用 Compose：

docker compose ps
docker compose logs --tail 100
docker compose restart

systemd 常用命令

systemctl status subconverter-extended
journalctl -u subconverter-extended -n 100 --no-pager
systemctl restart subconverter-extended

OpenWrt 常用命令

/etc/init.d/subconverter-extended status
/etc/init.d/subconverter-extended restart
logread -e subconverter

优雅停机

服务处理 SIGTERM、SIGINT，以及 POSIX 下的 SIGHUP、SIGQUIT，并尝试停止接收、结束后台任务和刷新统计。

容器和 systemd 应先发送正常停止信号。只在进程无法退出且已经保留诊断信息后，才使用强制终止。

配置变更

推荐流程：

1. 备份当前配置。
2. 在副本中修改。
3. 检查 TOML/YAML/INI 语法。
4. 重启服务。
5. 检查启动日志中的最终生效值。
6. 执行真实 /sub 请求。

不要只根据文件内容判断环境变量是否覆盖了配置。

备份范围

至少包括：

• 实际使用的主配置文件；
• 自定义本地模板、规则和脚本；
• Gist 或其他外部服务所需的单独秘密配置；
• 统计 data_dir；
• Docker Compose、systemd 单元或 OpenWrt 启动配置；
• 反向代理和访问控制配置。

镜像和程序包可以重新下载，不应替代配置备份。

资源观察

资源较小的主机应观察：

• RSS 和 OOM 状态；
• HTTP 和规则任务线程数；
• 文件描述符；
• 容器日志和统计目录大小；
• 高峰请求延迟和 5xx；
• 外部抓取超时。

调整 [advanced] 前先确定瓶颈。盲目增大 max_server_threads、关闭有界限制或增加缓存 TTL，可能提高内存和陈旧响应风险。

更新

Docker、OpenWrt 和便携版的无人值守更新见自动升级。手动升级、固定版本和回滚步骤见升级、回滚与迁移。更新当前实例前，先备份配置和统计数据，并记录版本身份。

告警建议

可以监控：

• /version 无法访问；
• 真实公开测试 /sub 失败；
• 容器重启次数增加；
• OOMKilled；
• SECURITY_PROFILE_INVALID_FALLBACK；
• 连续外部配置或规则抓取失败；
• Dashboard 登录锁定异常增加；
• 磁盘空间不足。

告警样例中不要嵌入真实订阅或凭据。