TeleBox 一键 Docker 安装文档

本安装方案实现：

• 首次登录一次性输入验证码
• 之后完全一键启动，不再登录
• 代码自动 clone / update
• 数据与 session 持久化

本文档包含完整的 docker-compose.yml、目录结构、使用步骤。

---

📁 1. 创建目录结构

在任意安装目录执行：

mkdir -p telebox-config telebox-session telebox-assets telebox-plugins telebox-logs telebox-temp

---

📄 2. 创建 config.json

编辑：

nano telebox-config/config.json

内容示例：

{
  "api_id": 123456,
  "api_hash": "your_api_hash_here"
}

登录时会自动生成 session，因此这里不要加 session 字段。

---

📦 3. 使用下方最终版 docker-compose.yml

将以下内容保存为 compose.yml：

services:
  # 正式运行的 TeleBox
  telebox:
    container_name: telebox
    image: node:20-bookworm
    working_dir: /opt/telebox/app
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - TB_PREFIX=. 。
      - TB_SUDO_PREFIX=# $
      - TB_CMD_IGNORE_EDITED=false
      - TB_LISTENER_HANDLE_EDITED=sudo sure

    volumes:
      - ./telebox-app:/opt/telebox/app
      - ./telebox-config/config.json:/opt/telebox/vol/config.json
      - ./telebox-session:/opt/telebox/vol/my_session
      - ./telebox-assets:/opt/telebox/vol/assets
      - ./telebox-plugins:/opt/telebox/app/plugins
      - ./telebox-logs:/opt/telebox/vol/logs
      - ./telebox-temp:/opt/telebox/vol/temp

    user: "0:0"

    command: >
      bash -lc "
        set -e;

        if ! command -v git > /dev/null 2>&1; then
          apt-get update &&
          apt-get install -y --no-install-recommends git ca-certificates &&
          rm -rf /var/lib/apt/lists/*;
        fi &&

        mkdir -p /opt/telebox/app /opt/telebox/vol &&

        if [ ! -d /opt/telebox/app/.git ]; then
          echo '>> Cloning TeleBox...';
          git clone https://github.com/TeleBoxOrg/TeleBox.git /opt/telebox/app;
        else
          echo '>> Updating TeleBox...';
          cd /opt/telebox/app &&
          git fetch origin &&
          git reset --hard origin/\$(git rev-parse --abbrev-ref HEAD);
        fi &&

        cd /opt/telebox/app &&

        # 强制重建软链接，确保指向 vol 持久化目录
        rm -rf config.json my_session assets logs temp &&
        ln -sf /opt/telebox/vol/config.json config.json &&
        ln -sf /opt/telebox/vol/my_session my_session &&
        ln -sf /opt/telebox/vol/assets assets &&
        ln -sf /opt/telebox/vol/logs logs &&
        ln -sf /opt/telebox/vol/temp temp &&

        echo '>> Installing npm dependencies...';
        npm install &&

        unset NODE_OPTIONS &&

        echo '>> Starting TeleBox...';
        npm run start
      "

  # 专门用来"第一次登录"的交互式容器
  telebox-login:
    image: node:20-bookworm
    working_dir: /opt/telebox/app
    profiles:
      - login
    stdin_open: true
    tty: true
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./telebox-app:/opt/telebox/app
      - ./telebox-config/config.json:/opt/telebox/vol/config.json
      - ./telebox-session:/opt/telebox/vol/my_session
      - ./telebox-assets:/opt/telebox/vol/assets
      - ./telebox-plugins:/opt/telebox/app/plugins
      - ./telebox-logs:/opt/telebox/vol/logs
      - ./telebox-temp:/opt/telebox/vol/temp

    user: "0:0"

    command: >
      bash -lc "
        set -e;

        if ! command -v git > /dev/null 2>&1; then
          apt-get update &&
          apt-get install -y --no-install-recommends git ca-certificates &&
          rm -rf /var/lib/apt/lists/*;
        fi &&

        mkdir -p /opt/telebox/app /opt/telebox/vol &&

        if [ ! -d /opt/telebox/app/.git ]; then
          echo '>> Cloning TeleBox...';
          git clone https://github.com/TeleBoxOrg/TeleBox.git /opt/telebox/app;
        else
          echo '>> Updating TeleBox...';
          cd /opt/telebox/app &&
          git fetch origin &&
          git reset --hard origin/\$(git rev-parse --abbrev-ref HEAD);
        fi &&

        cd /opt/telebox/app &&

        # 强制重建软链接
        rm -rf config.json my_session assets logs temp &&
        ln -sf /opt/telebox/vol/config.json config.json &&
        ln -sf /opt/telebox/vol/my_session my_session &&
        ln -sf /opt/telebox/vol/assets assets &&
        ln -sf /opt/telebox/vol/logs logs &&
        ln -sf /opt/telebox/vol/temp temp &&

        echo '>> Installing npm dependencies...';
        npm install &&

        unset NODE_OPTIONS &&

        echo '>> Starting TeleBox for FIRST LOGIN...';
        npm run start
      "

---

🔑 4. 进行第一次登录（必须做一次）

docker compose --profile login run --rm telebox-login

进入交互界面后按提示输入：

1. 你的 Telegram 手机号
2. 收到的 验证码
3. （如果设置过）2FA 密码

出现登录成功提示后按：

CTRL + C

退出即可。

会话已经写入 ./telebox-session，以后永远不需要再次登录。

---

🚀 5. 启动正式服务

docker compose up -d telebox

查看运行日志：

docker logs -f telebox

若 bot 正常上线，则安装完成。

---

🔄 6. 更新 TeleBox（可选）

以后只需：

docker compose down
docker compose up -d

容器会自动执行 git pull + 更新依赖。

---

🎉 安装完成！

如需继续优化：

• 加健康检查
• 自动重启保护
• 日志分离
• 多账号共存

告诉我即可，我可以继续帮你完善配置。