Docker Deployment

🐳 Docker 部署

Docker 是推荐的自行部署方式。正式 Release 对应的 latest 镜像发布到：

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

latest 镜像支持 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

仅在配置不存在时，从 latest 镜像导出与当前 Release 配套的示例：

if [ ! -f base/pref.toml ]; then
  docker run --rm \
    --entrypoint cat \
    aethersailor/subconverter-extended:latest \
    /base/pref.example.toml > base/pref.toml
fi

已有 base/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

创建 docker-compose.yml：

services:
  subconverter-extended:
    container_name: SubConverter-Extended
    image: aethersailor/subconverter-extended:latest
    ports:
      - "25500:25500/tcp"
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    volumes:
      - "./base/pref.toml:/base/pref.toml:ro"
      - "./stats:/base/stats"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

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

docker compose config
docker compose up -d
docker compose ps

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

环境变量覆盖

常用环境变量：

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

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

更新

需要自动跟随正式 Release 时，建议部署 Watchtower，并仅允许它更新 SubConverter-Extended 容器。完整配置、风险说明和验证步骤见自动升级。

手动更新：

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"

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