Docker Deployment

Docker 部署

Docker 是推荐的长期部署方式。稳定镜像发布到：

aethersailor/subconverter-extended
ghcr.io/aethersailor/subconverter-extended

稳定镜像支持 linux/amd64、linux/arm64 和 linux/arm/v7。

部署前检查

• 已安装 Docker，能够运行 docker version。
• 已决定服务只供本机、局域网还是公网访问。
• 已准备持久化配置和统计目录。
• 公网部署已阅读安全与隐私和反向代理与公网部署。

1. 创建目录

mkdir -p /opt/SubConverter-Extended/base
mkdir -p /opt/SubConverter-Extended/stats
cd /opt/SubConverter-Extended

仅在配置不存在时下载示例：

if [ ! -f base/pref.toml ]; then
  curl -fL \
    https://raw.githubusercontent.com/Aethersailor/SubConverter-Extended/master/base/pref.example.toml \
    -o base/pref.toml
fi

不要反复下载并覆盖现有 pref.toml。

2. 修改必要配置

如果其他设备需要访问服务，将 managed_config_prefix 改为实际地址：

[managed_config]
managed_config_prefix = "http://192.168.1.10:25500"

公网部署还应显式设置：

[security]
profile = "public"
allow_public_upload = false

3. 启动容器

局域网访问：

docker run -d \
  --name SubConverter-Extended \
  -p 25500:25500 \
  -v /opt/SubConverter-Extended/base/pref.toml:/base/pref.toml:ro \
  -v /opt/SubConverter-Extended/stats:/base/stats \
  --restart unless-stopped \
  aethersailor/subconverter-extended:latest

只允许宿主机和本机反向代理访问时，将端口改为：

-p 127.0.0.1:25500:25500

Warning

-p 25500:25500 会发布到宿主机全部接口，但程序无法判断宿主防火墙、云安全组、NAT 或反向代理是否已经让它公网可达。不要把 lan 默认档位当作公网保护。

4. 验证服务

curl -f http://127.0.0.1:25500/healthz
curl -f http://127.0.0.1:25500/version

预期结果：/healthz 返回 ok，/version 返回版本页面。随后执行一次不含秘密的真实 /sub 请求，确认转换路径可用。

查看日志：

docker logs --tail 100 SubConverter-Extended

Docker Compose

下载示例：

cd /opt/SubConverter-Extended
curl -fL \
  https://raw.githubusercontent.com/Aethersailor/SubConverter-Extended/master/docker-compose.yml \
  -o docker-compose.yml

确认 base/pref.toml 已存在后启动：

docker compose config
docker compose up -d
docker compose ps

仓库示例持久化：

volumes:
  - "./base/pref.toml:/base/pref.toml:ro"
  - "./stats:/base/stats"

不要把整个宿主机 base 目录挂载到容器 /base。这样会遮盖镜像内随版本更新的规则、模板和其他运行文件。

环境变量覆盖

常用环境变量：

environment:
  MANAGED_CONFIG_PREFIX: "https://sub.example.com"
  SUBCONVERTER_SECURITY_PROFILE: public
  SUBCONVERTER_ALLOW_PUBLIC_UPLOAD: "false"

环境变量会覆盖对应的配置文件值。完整列表见配置文件参考。

更新

cd /opt/SubConverter-Extended
docker compose pull
docker compose up -d

使用 docker run 时：

docker pull aethersailor/subconverter-extended:latest
docker rm -f SubConverter-Extended
# 使用原启动参数重新创建容器

删除容器前确认配置和统计数据位于宿主机。需要固定版本和回滚时，不要只依赖 latest；见升级、回滚与迁移。

日志限制

仓库 Compose 示例使用 Docker json-file 日志，并设置：

logging:
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

这些值只限制容器标准日志，不会备份配置或统计数据。