服务器运维

服务器安装

使用 Docker Compose 在一台公网服务器上安装和运营 Pabal 服务器的方法。

本文介绍如何把 Pabal 服务器安装到一台公网服务器上。用 Docker Compose 启动 Pabal 服务器 · PostgreSQL · Caddy（HTTPS）三个容器，所有不能丢失的数据都绑定挂载到主机目录。从上到下依次照做即可。

整体概览

准备工作

端口

1. 准备服务器

sudo apt update && sudo apt -y upgrade
timedatectl                      # 确认显示 "System clock synchronized: yes"

时间同步是必需的。MTProto 的消息编号由时间生成，服务器时钟不准时，应用会反复重新连接。如果显示 no，请执行 sudo timedatectl set-ntp true。

# 防火墙
sudo ufw allow OpenSSH           # 如果可以：sudo ufw allow from <运营方 IP> to any port 22
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw allow 8443/tcp
sudo ufw enable

# Docker（官方安装脚本）
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER     # 重新登录后无需 sudo 即可使用 docker
docker compose version            # v2 及以上

2. 获取源代码

sudo mkdir -p /opt/pabal && sudo chown $USER: /opt/pabal
git clone <仓库地址> /opt/pabal

如果从开发电脑复制，不要把密钥、数据和日志传过去（rsync --exclude 'keys/' --exclude 'data/' --exclude 'logs/' --exclude '**/target/'）。运营服务器的 RSA 密钥会在运营服务器首次启动时重新生成——如果在运营环境中使用开发用的密钥，那台开发电脑就成了能够解密运营流量的地方。

3. 数据目录（绑定挂载）

sudo mkdir -p /srv/pabal/{postgres_data,pabal_server/keys,pabal_server/data,pabal_server/logs,caddy/data,caddy/config,backups}
sudo chown -R 1000:1000 /srv/pabal/pabal_server        # 服务器容器以 uid 1000 运行
sudo chown -R $USER: /srv/pabal/backups
sudo chmod 700 /srv/pabal/pabal_server/keys /srv/pabal/backups

4. 配置文件 .env

cd /opt/pabal/deploy
cp .env.example .env
chmod 600 .env
openssl rand -base64 30 | tr -d '/+=' | cut -c1-32     # 把输出的值填入 POSTGRES_PASSWORD
nano .env

DOMAIN=pabal.me
PUBLIC_IP=203.0.113.10
POSTGRES_PASSWORD=(上面生成的值)
PABAL_HOME=/srv/pabal
PABAL_SOURCE=..
PABAL_NETWORK=ssemiya-net
MTPROTO_PORT=8443
HTTP_PORT=80
HTTPS_PORT=443
ADMIN_PORT=8080
ADMIN_TOKEN=
JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=100"

正式运营用的 Compose 文件会在关闭测试号码的状态下（TELEGRAM_TEST_NUMBERS=false）启动服务器。服务器读取的全部设置项，请参阅管理与设置——环境变量。

5. DNS

dig +short pabal.me        # 应该输出 203.0.113.10（生效需要几分钟到几小时）

在 DNS 指向这台服务器之前启动也没关系。Caddy 会自动重试，直到拿到证书为止。

6. 构建并启动

cd /opt/pabal/deploy
docker network inspect ssemiya-net >/dev/null 2>&1 || docker network create ssemiya-net   # 只需一次
docker compose up -d --build       # 第一次需要几分钟（Maven 会下载依赖库）
docker compose ps                  # pabal-server、pabal-postgres、pabal-caddy 为 running (healthy)
docker compose logs -f pabal-server      # 按 Ctrl+C 退出

首次启动时，日志中会出现如下几行。

WARN  ServerKeys - Generated a new RSA key at /app/keys/private.pem (fingerprint -3898654385185406269). Clients must embed /app/keys/private.pem.pub
INFO  TelegramServer - JDBC persistence active (jdbc:postgresql://pabal-postgres:5432/pabal)
INFO  BotFather - BotFather is user 100000
INFO  AdminToken - Created the admin token in /app/data/admin-token
INFO  TelegramServer - Website: http://0.0.0.0:8080/ (published at https://pabal.me/)

• 第一行虽然是 WARN，但属于正常情况（只是告知首次生成了密钥，只会出现一次）。之后会显示 Loaded RSA key … (fingerprint …)。fingerprint 因服务器而异。
• 数据表会在服务器启动时自动创建。

7. 验证

# 在外部（自己的电脑）执行
curl -sI https://pabal.me/ | head -1                              # HTTP/2 200
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/docs/    # 200 — 本文档
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/admin/   # 404 — 管理页面不对外公开
curl -s https://pabal.me/docs/server-key.pem | head -1             # -----BEGIN RSA PUBLIC KEY-----
nc -vz 203.0.113.10 8443                                          # succeeded — 应用端口

# 在服务器上执行
curl -s http://127.0.0.1:8080/health          # {"status":"UP",…}
ls -l /srv/pabal/pabal_server/keys                  # private.pem(600), private.pem.pub

8. 管理页面与初始设置

# 在自己的电脑上执行（保持运行）
ssh -N -L 8080:127.0.0.1:8080 <用户>@203.0.113.10

# 令牌在服务器上查看
sudo cat /srv/pabal/pabal_server/data/admin-token

在浏览器中打开 http://localhost:8080/admin/，输入令牌。正式运营前一定要完成的设置（详见管理与设置）：

1. 把验证码发送方式（코드 전달 방식）设为短信或电子邮件。“管理页面”（관리 화면）方式需要运营方逐一告知验证码。
2. 填入 SMS 或电子邮件（SMTP）（이메일 (SMTP)）的设置值并保存 → 用测试发送（테스트 발송）确认确实能够收到。
3. 确认测试号码（테스트 번호）已关闭。开启后，任何人都能用 +99966… 号码登录。
4. 如有需要，可以先关闭允许新注册（새 가입 허용）再开始，只让受邀的人先加入。

9. 让应用连接这台服务器

应用在构建时会内置服务器 IP · 端口 · 公钥。必须用这台服务器的公钥重新构建，应用才能连接这台服务器。在 Mac 上执行：

# 1. 这台服务器的公钥（是公钥而不是私钥——也可以从文档网站下载）
curl -s -o keys/production.pem.pub https://pabal.me/docs/server-key.pem

# 2. 让应用源代码指向这台服务器 + 应用品牌
python3 scripts/tdesktop/point_to_server.py ~/Developer/tdesktop \
    --host 203.0.113.10 --port 8443 --key keys/production.pem.pub
python3 scripts/tdesktop/apply_branding.py ~/Developer/tdesktop

然后执行仓库中 docs/tdesktop-build-guide.md 的第 5 步（configure）和第 6 步（构建）。请把生成的 out/Debug/Pabal.app 以其他名称另行复制保存——用同一份源代码为另一台服务器重新构建时，它会被覆盖。

运维

状态与日志

cd /opt/pabal/deploy
docker compose ps
docker compose logs --since 1h pabal-server
tail -f /srv/pabal/pabal_server/logs/telegram-server.log

更新

cd /opt/pabal && git pull
cd deploy
./backup.sh                                     # 先备份
docker compose up -d --build pabal-server             # 用新镜像只替换服务器
docker compose logs --since 5m pabal-server | grep -E "Website|ERROR"

在服务器重启的几十秒内，应用会断开，然后无需重新登录就会自动重新连接。数据表的变更会在服务器启动时自动应用。绑定目录与镜像无关，因此 docker compose down 或删除镜像都不会删除数据——只要不删除 /srv/pabal 就行。

备份

./backup.sh            # → /srv/pabal/backups/<日期-时间>/{pabal.dump, server-keys-data.tar.gz}
crontab -e             # 每天 03:00：
# 0 3 * * * /opt/pabal/deploy/backup.sh >> /srv/pabal/backups/backup.log 2>&1

• 超过 14 天的备份会被自动删除（可以像 KEEP_DAYS=30 ./backup.sh 这样修改）。
• 请同时复制到其他地方。放在同一块磁盘上的备份扛不住磁盘故障。
• 备份中包含 RSA 私钥以及短信、SMTP 的机密值。存放备份的地方也要像服务器一样严加保护。

恢复

cd /opt/pabal/deploy
B=/srv/pabal/backups/20260920-030000            # 要恢复的备份
docker compose stop pabal-server pabal-caddy
docker compose exec -T pabal-postgres dropdb -U pabal pabal
docker compose exec -T pabal-postgres createdb -U pabal pabal
docker compose exec -T pabal-postgres pg_restore -U pabal -d pabal --no-owner < $B/pabal.dump
sudo tar -C /srv/pabal/pabal_server -xzf $B/server-keys-data.tar.gz
sudo chown -R 1000:1000 /srv/pabal/pabal_server
docker compose up -d

迁移到新服务器时也一样：完成第 1~5 步后，不执行第 6 步，而是执行上面的恢复再启动。恢复同一个密钥后，就不需要重新构建应用（如果服务器 IP 变了，则需要重新构建）。

启动与停止

docker compose restart pabal-server       # 只重启服务器
docker compose stop                 # 全部停止（数据保持不变）
docker compose up -d                # 重新启动

即使服务器主机重启，容器也因为设置了 restart: unless-stopped 而会自动重新启动。

安全检查清单

• .env 权限为 600，POSTGRES_PASSWORD 为随机值
• /srv/pabal/pabal_server/keys 权限为 700，私钥除了备份之外不存在于其他任何地方
• 防火墙：只开放 22（尽量只对运营方 IP）、80、443、8443
• 从外部访问 https://域名/admin/ 返回 404
• 管理页面：测试号码（테스트 번호）已关闭，验证码发送方式（코드 전달 방식）为短信/电子邮件，测试发送（테스트 발송）成功
• 没有开启 TELEGRAM_WEBHOOK_ALLOW_LOCAL（防止机器人 Webhook 访问内部网络）
• SSH：关闭密码登录，只允许密钥登录
• 确认备份 cron 和外部复制，并演练一次恢复
• 开启服务器操作系统的自动安全更新（unattended-upgrades）

故障排除

已知限制

• 单服务器架构。启动时会把所有账号、对话和消息加载到内存中。暂不支持拆分到多台服务器的水平扩展，数据增多时需要增加内存。
• 等待中的注册验证码、机器人尚未取走的更新保存在内存中，服务器重启后就会丢失。
• 注册验证码的请求有间隔和每日上限，但其他所有请求都还没有频率限制。刚对外公开后，请经常查看日志和仪表盘。
• 没有手机应用和推送通知。消息附件只支持照片。频道、超级群组和两步验证尚未支持。
• 授权密钥以明文形式保存在数据库中（服务器解密时需要）。请像保护 RSA 密钥一样保护数据库和备份。

文件