mnday/trojan-main repository overview

⁠Trojan Main

Trojan Main 是一个集成 Trojan 服务、Web 管理面板、用户面板、节点同步与 MariaDB 数据存储的 Docker 化管理系统。镜像同时支持 linux/amd64 与 linux/arm64。

⁠主要功能

• 管理员面板：用户、卡券、节点、系统配置和日志审计
• 用户面板：流量与有效期、客户端下载、礼品卡兑换、账户安全
• 密码与 OTP 二次验证
• 主服务器与多个 Trojan Node 节点之间的用户及流量同步
• 节点连接测试、手工同步和实时同步日志
• Uptime Kuma 服务状态展示
• MariaDB Event Scheduler：用户状态、流量重置及日志清理
• 审计日志和节点同步日志默认保留 90 天

⁠运行要求

• Docker Engine 24 或更新版本
• Docker Compose v2
• 两个均已解析到服务器公网 IP 的不同域名：一个用于 Trojan，一个用于 Panel
• 对外开放 80/tcp 和 443/tcp；两项服务通过 SNI 共享公网 443
• 建议至少 1 GB 内存

⁠Docker Compose 部署

先创建共享网络：

docker network create proxy_network

在部署目录创建 docker-compose.yaml：

services:
  mariadb:
    image: mariadb:latest
    container_name: trojan_db
    restart: always
    environment:
      TZ: Asia/Shanghai
      MARIADB_DATABASE: trojan
      MARIADB_ROOT_PASSWORD: 请替换为高强度数据库密码
    command:
      - --event-scheduler=ON
      - --default-time-zone=+08:00
    volumes:
      - ./db_data:/var/lib/mysql
    networks:
      - proxy_network

  trojan:
    image: mnday/trojan-main:latest
    container_name: trojan
    restart: always
    depends_on:
      - mariadb
    environment:
      TZ: Asia/Shanghai
      # 默认不需要配置。设为 true 会停止自动节点同步调度器。
      DISABLE_NODE_SYNC: "false"
    ports:
      - "443:443"
      - "80:80"
    dns:
      - 1.1.1.1
      - 8.8.8.8
    volumes:
      - ./conf/trojan:/usr/local/etc/trojan
      - ./conf/panel:/usr/local/etc/panel
      - ./conf/nginx:/etc/nginx
      - ./conf/certs:/root/certs:ro
      - ./conf/acme:/root/.acme.sh
    networks:
      - proxy_network

networks:
  proxy_network:
    name: proxy_network
    external: true

启动容器：

docker compose up -d

首次启动时，如果 Trojan 配置仍是模板状态，容器会等待初始化。运行安装向导：

docker exec -it trojan install

向导会要求输入 Trojan 域名、Panel 域名、证书方式、两个内部监听端口、数据库连接信息和管理员账户。默认内部端口为：

• Trojan：5678
• Panel HTTPS：4443

两个内部端口不会发布到公网；公网入口固定为 Nginx 443。安装向导会申请或验证一张同时覆盖两个域名的证书，并生成如下 SNI 分流：

Trojan 域名:443 → Trojan 内部端口
Panel 域名:443  → Panel 内部 HTTPS 端口

上面示例对应的数据库信息为：

• 数据库容器名称：trojan_db
• 数据库名称：trojan
• 数据库密码：MARIADB_ROOT_PASSWORD 设置的值

初始化完成后访问：

https://Panel 域名/

./conf/nginx 会整体映射到容器的 /etc/nginx。首次启动只会创建 ./conf/nginx/nginx.conf，之后 install.sh 直接更新该文件。用户可以在宿主机修改它并重启容器，以扩展其他 SNI 或反向代理服务。default.conf、mime.types 等固定依赖均位于镜像内部，不写入持久化目录，也不需要用户维护。

⁠持久化目录

./conf/panel/.panel-secret 会在首次初始化或 API 首次启动时自动生成。JWT 签名密钥和 OTP 加密密钥均由它派生。必须长期持久化并纳入备份；丢失或更换该文件会导致现有登录令牌失效，并可能导致已绑定的 OTP 无法解密。

请勿将 db_data、证书、.panel-secret 或包含真实密码的配置提交到 Git。

⁠节点同步

同步系统包含两层开关：

1. 全局自动同步调度器
2. 每个节点自身的启用状态

⁠全局开关

全局调度器由主容器环境变量控制：

environment:
  DISABLE_NODE_SYNC: "true"

• 不配置或设置为 "false"：启动自动同步
• 设置为 "true"：关闭自动同步调度器

该变量在 API 进程启动时读取，修改后必须重建或重启主容器：

docker compose up -d --force-recreate trojan

它是部署级紧急开关，目前不在管理页面中修改。管理员首页会显示调度器的真实状态。

⁠单节点开关

管理员可在“节点管理 → 编辑节点”中启用或停用某个节点。单节点开关不会改变全局调度器状态。

启用自动同步需要同时满足：

• DISABLE_NODE_SYNC 不为 true
• 节点状态为启用
• 节点地址和 API 密钥正确
• 主服务器可以通过网络访问节点 API

同步流程：

1. 主服务器读取节点上的用户和流量数据。
2. 同步用户的新增、更新和删除状态。
3. 将节点流量合并到主服务器。
4. 合并成功后清空节点侧已上报流量。
5. 写入节点同步日志和审计日志。

上线前建议先使用“测试连接”，再执行一次“立即同步”，并通过实时日志确认完整过程。

⁠MariaDB Event Scheduler

数据库事件调度器必须保持开启，否则到期状态、周期流量重置和日志清理等事件不会按时执行。

检查状态：

SHOW VARIABLES LIKE 'event_scheduler';

SELECT EVENT_SCHEMA, EVENT_NAME, STATUS, LAST_EXECUTED
FROM information_schema.EVENTS
WHERE EVENT_SCHEMA = 'trojan';

临时开启：

SET GLOBAL event_scheduler = ON;

Docker Compose 中的持久化配置为：

command:
  - --event-scheduler=ON
  - --default-time-zone=+08:00

TZ=Asia/Shanghai 设置容器系统时区，--default-time-zone=+08:00 设置 MariaDB 默认时区，两者用途不同。

⁠账户安全

• 密码长度为 8–64 位
• 必须包含大写字母、小写字母和数字
• 符号可选
• 用户和管理员可自行绑定 TOTP OTP
• 管理员可在用户管理中重置用户 OTP
• 5 分钟内连续三次登录密码错误会禁止面板登录 60 分钟

登录风控只限制 Web 面板认证，不会停用 Trojan 用户，也不会改变用户的服务状态。

⁠备份与恢复

至少备份以下内容：

• MariaDB 的 trojan 数据库
• ./conf/trojan
• ./conf/panel
• 证书目录

导出数据库：

docker exec trojan_db mariadb-dump \
  -u root -p \
  --single-transaction --routines --events --triggers \
  trojan > trojan-backup.sql

使用 --events 非常重要，否则数据库事件不会包含在备份中。

恢复数据库：

docker exec -i trojan_db mariadb -u root -p trojan < trojan-backup.sql

恢复后检查事件调度器、数据库事件、用户数量、节点配置和最近同步日志。

⁠更新镜像

docker compose pull --policy always
docker compose up -d --force-recreate
docker compose ps
docker compose logs --tail=200 trojan

更新前请先备份数据库和 conf 目录。不要删除 db_data 或 conf/panel 后直接重建生产服务。

⁠常用检查命令

查看容器状态：

docker compose ps

查看主服务日志：

docker compose logs -f trojan

查看数据库日志：

docker compose logs -f mariadb

检查多架构镜像：

docker buildx imagetools inspect mnday/trojan-main:latest

检查数据库表：

CHECK TABLE
  trojan.users,
  trojan.nodes,
  trojan.gift_cards,
  trojan.node_sync_logs;

⁠常见问题

⁠节点已经启用，但首页显示全局同步已关闭

检查主容器的环境变量：

docker inspect trojan --format '{{range .Config.Env}}{{println .}}{{end}}' \
  | grep DISABLE_NODE_SYNC

如果输出 DISABLE_NODE_SYNC=true，请从 Compose 配置中删除该变量或改为 false，然后重新创建主容器。

⁠节点测试连接失败

依次检查：

• 主服务器能否解析节点域名
• 节点的 HTTPS/API 端口是否可达
• 防火墙、安全组及网络封锁
• 节点 API 密钥是否与管理面板中完全一致
• 节点证书是否有效

⁠修改镜像后页面仍是旧版本

docker compose pull --policy always
docker compose up -d --force-recreate

随后清除浏览器缓存或使用无痕窗口验证。

⁠OTP 在迁移后失效

确认迁移时同时恢复了 ./conf/panel/.panel-secret。仅恢复数据库但没有恢复该文件，无法解密原有 OTP 密钥。