快速开始
本指南介绍从版本包到首次登录的完整流程。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 后解压并进入目录:
unzip TGBotPress-main.zip
cd TGBotPress-main下载地址始终指向主分支最新内容;如果需要固定版本和对应的发布说明,请从发布页选择版本。压缩包目录名称不同,以实际解压出的目录为准。
方式 B:克隆仓库
git clone https://github.com/cnmbdb/TGBotPress.git
cd TGBotPress确认目录中存在 `docker-compose.yml`、`.env.example` 和 `Dockerfile`,再继续配置。
3. 创建环境配置
复制环境变量模板:
cp .env.example .env编辑 `.env`,至少设置以下值:
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. 拉取并启动服务
docker compose pull
docker compose up -d
docker compose ps查看应用启动日志,确认数据库初始化和迁移完成:
docker compose logs -f platform首次启动空数据库时,镜像会创建基础表并执行迁移。Compose 会创建并持久化以下数据:
- `postgres_data`:PostgreSQL 数据库。
- `media`:应用媒体文件。
不要在已有数据的部署上运行 `docker compose down -v`,因为 `-v` 会删除命名卷。
5. 检查健康状态并登录
先确认容器状态:
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 隧道访问:
ssh -L 8083:127.0.0.1:8083 user@your-server然后在本机打开上述登录地址。正式环境应通过宝塔或 Nginx 配置 HTTPS 反向代理,并将 `PLATFORM_ORIGIN` 同步为实际域名。
初始密码和密钥
`ADMIN_INITIAL_PASSWORD` 只在空数据库首次初始化时使用,修改环境变量不会重置已有账号密码。请同时备份数据库卷和 `APP_KEY`;不要通过删除数据卷来解决登录问题。
6. 更新版本
更新前先备份 PostgreSQL 和媒体卷,并在隔离环境验证目标版本。使用固定版本时,先修改 `TGBOTPRESS_IMAGE`,再拉取并重建应用:
docker compose pull platform
docker compose up -d platform
docker compose logs -f platform如果使用 `latest`,镜像会随主分支构建更新;生产环境建议改用已验证的版本标签或发布包,并记录迁移结果。
常见启动问题
镜像拉取失败
检查服务器是否能访问 GHCR 和 Docker Hub。GHCR 包如果是私有的,需要先使用具有读取权限的 GitHub 账号登录;不要把凭据写入 Compose 文件或提交到仓库。
应用容器反复重启
依次查看应用和数据库日志:
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 官方部署文档。