Skip to content

快速开始 ​

本指南介绍从版本包到首次登录的完整流程。TGBotPress 推荐使用已经发布的版本包或 Docker 镜像部署;源码开发请参考项目仓库中的开发说明。

1. 准备环境 ​

部署机器需要满足以下条件:

  • 安装 Docker 和 Docker Compose 插件。
  • 可以拉取 `ghcr.io/cnmbdb/tgbotpress:latest`、`postgres:16` 和 `redis:7-alpine` 镜像。
  • 准备一个新的空 PostgreSQL 数据库,或允许 Compose 创建数据库容器。
  • 准备独立的数据库密码、管理员初始密码和应用密钥。

本教程使用 Compose 同时运行应用、PostgreSQL 和 Redis。应用端口只绑定到服务器本机,适合先在本机或反向代理后验证。

2. 获取项目文件 ​

方式 A:下载版本包 ​

使用下面的按钮下载 GitHub 主分支的最新项目包,或打开 TGBotPress Releases 选择已经发布的版本。下载 ZIP 后解压并进入目录:

sh
unzip TGBotPress-main.zip
cd TGBotPress-main

下载地址始终指向主分支最新内容;如果需要固定版本和对应的发布说明,请从发布页选择版本。压缩包目录名称不同,以实际解压出的目录为准。

方式 B:克隆仓库 ​

sh
git clone https://github.com/cnmbdb/TGBotPress.git
cd TGBotPress

确认目录中存在 `docker-compose.yml`、`.env.example` 和 `Dockerfile`,再继续配置。

3. 创建环境配置 ​

复制环境变量模板:

sh
cp .env.example .env

编辑 `.env`,至少设置以下值:

dotenv
DB_PASSWORD=替换为强随机数据库密码
ADMIN_INITIAL_PASSWORD=替换为强随机管理员密码
APP_KEY=替换为至少32个字符的独立随机密钥
PLATFORM_ORIGIN=http://127.0.0.1:8083
TGBOTPRESS_IMAGE=ghcr.io/cnmbdb/tgbotpress:latest

可以分别使用 `openssl rand -hex 32` 生成数据库密码和应用密钥。管理员密码至少 12 个非空白字符,最多 72 个 UTF-8 字节;不要在多个用途之间复用密钥,也不要把 `.env` 提交到 Git。

使用域名和 HTTPS 时,将 `PLATFORM_ORIGIN` 改为浏览器实际访问的完整 origin,例如 `https://bot.example.com`。数据库连接、Telegram 和业务开关见配置指南。

4. 拉取并启动服务 ​

sh
docker compose pull
docker compose up -d
docker compose ps

查看应用启动日志,确认数据库初始化和迁移完成:

sh
docker compose logs -f platform

首次启动空数据库时,镜像会创建基础表并执行迁移。Compose 会创建并持久化以下数据:

  • `postgres_data`:PostgreSQL 数据库。
  • `media`:应用媒体文件。

不要在已有数据的部署上运行 `docker compose down -v`,因为 `-v` 会删除命名卷。

5. 检查健康状态并登录 ​

先确认容器状态:

sh
docker compose ps
curl -fsS http://127.0.0.1:8083/api/health

浏览器打开 http://127.0.0.1:8083/login。空数据库首次初始化时,管理员账号为 `trxadmin`,密码是 `.env` 中的 `ADMIN_INITIAL_PASSWORD`。

远程服务器不建议直接暴露 8083 端口。可以使用 SSH 隧道访问:

sh
ssh -L 8083:127.0.0.1:8083 user@your-server

然后在本机打开上述登录地址。正式环境应通过宝塔或 Nginx 配置 HTTPS 反向代理,并将 `PLATFORM_ORIGIN` 同步为实际域名。

初始密码和密钥

`ADMIN_INITIAL_PASSWORD` 只在空数据库首次初始化时使用,修改环境变量不会重置已有账号密码。请同时备份数据库卷和 `APP_KEY`;不要通过删除数据卷来解决登录问题。

6. 更新版本 ​

更新前先备份 PostgreSQL 和媒体卷,并在隔离环境验证目标版本。使用固定版本时,先修改 `TGBOTPRESS_IMAGE`,再拉取并重建应用:

sh
docker compose pull platform
docker compose up -d platform
docker compose logs -f platform

如果使用 `latest`,镜像会随主分支构建更新;生产环境建议改用已验证的版本标签或发布包,并记录迁移结果。

常见启动问题 ​

镜像拉取失败 ​

检查服务器是否能访问 GHCR 和 Docker Hub。GHCR 包如果是私有的,需要先使用具有读取权限的 GitHub 账号登录;不要把凭据写入 Compose 文件或提交到仓库。

应用容器反复重启 ​

依次查看应用和数据库日志:

sh
docker compose logs --tail=200 platform
docker compose logs --tail=200 postgres

重点检查 `DB_PASSWORD` 是否一致、PostgreSQL 是否 healthy、`APP_KEY` 是否达到长度要求,以及空库初始化和迁移是否报错。

登录密码不生效 ​

确认数据库不是已有数据。`ADMIN_INITIAL_PASSWORD` 只在空数据库第一次初始化时读取;已有账号需要使用项目提供的账号管理流程处理,不要删除数据卷。

Telegram 没有收到更新 ​

健康检查通过只代表基座可访问。Telegram Webhook 还需要公网 HTTPS 地址、正确的路由、稳定密钥以及对应的 Telegram 开关;请先在受控环境验证,再启用轮询或 Webhook。

更多数据库、宝塔和进程模式说明见配置指南及 TGBotPress 官方部署文档。

Released under the MIT License.