Telegram-Panel/docs/getting-started/installation.md

安装部署

本文档用于把 Telegram Panel 跑起来（推荐 Docker 远程镜像）。

Docker 部署（推荐）

环境要求

• Docker（Windows 推荐 Docker Desktop + WSL2；Linux 直接安装 Docker Engine）

第一步：准备项目

git clone https://github.com/moeacgx/Telegram-Panel
cd Telegram-Panel
cp .env.example .env

第二步：选择镜像版本

默认是稳定版（无需改动）：

TP_IMAGE=ghcr.io/moeacgx/telegram-panel:latest

如果你要开发版，把 .env 里的 TP_IMAGE 改成：

TP_IMAGE=ghcr.io/moeacgx/telegram-panel:dev-latest

第三步：启动

docker compose pull
docker compose up -d

启动后访问：http://localhost:5000

默认后台账号（首次登录）

• 用户名：tgpanel
• 密码：tgpanel123

登录后到「修改密码」页面改掉即可。

必做配置：Telegram API 凭据

到 https://my.telegram.org/apps 用任意一个 Telegram 账号申请一次 api_id / api_hash，然后在面板「系统设置」里保存即可。

说明：不需要每个账号都申请，全站共用这一对即可工作。
注意：api_hash 是 32 位十六进制字符串（0-9a-f），请不要填 Token/用户名/URL 等其它值。

导入或登录前先选择账号出口

导入账号、手机号登录和二维码登录会在第一条 Telegram 请求前要求选择代理出口、有效的 全局代理或明确直连。账号导入可以自动分配已有 WARP，但不会为每个账号新建容器；登录 仍可按需一键创建独立 WARP。系统不会先用面板公网 IP 登录，再补绑代理。

普通 HTTP、SOCKS5、MTProxy 和 Resin 可直接在 代理管理 中添加。需要面板一键创建 WARP 时，使用受管 WARP 叠加配置：

docker compose -f docker-compose.yml -f docker-compose.warp.yml up -d

该配置会挂载 Docker Socket，仅应在可信主机启用。完整说明见 代理管理与账号出口。

数据持久化（别乱删）

容器内所有持久化数据统一挂载到宿主机 ./docker-data：

• 数据库：./docker-data/telegram-panel.db
• Sessions：./docker-data/sessions/
• 系统设置本地覆盖：./docker-data/appsettings.local.json
• 后台登录凭据文件：./docker-data/admin_auth.json
• 图片资产：./docker-data/uploads/

更多说明见：配置与数据目录。

常用命令

# 查看日志
docker compose logs -f

# 更新到当前 .env 指定的镜像版本
docker compose pull
docker compose up -d

# 重启 / 停止
docker compose restart
docker compose down

生产部署入口

• 反向代理（含 WebSocket）：见 反向代理
• Bot Webhook（可选，生产推荐）：见 Bot Webhook

更新与常见问题

• 更新升级：见 更新升级
• 常见问题：见 常见问题
• 如果出现“镜像已更新但页面还是旧版”，请看 更新升级 里的 「常见现象：镜像更新了，页面还是旧版」与「远程镜像 与 本地构建：如何切换」。

下一步

• 账号导入：见 账号导入（Zip / TData）
• 新号必看：见 防冻结指南
• 列表/批量能力依赖同步：见 同步说明

本地开发运行（可选）

corepack enable
pnpm --dir frontend install --frozen-lockfile
pnpm --dir frontend run build
dotnet run --project src/TelegramPanel.Web