服务器运维
管理与设置
管理页面、注册验证码的发送（短信和电子邮件）、服务器设置值、备份与安全——面向运营方的参考。
服务器内置了一个用浏览器打开的管理页面。你可以在这里查看服务器状态，决定如何发送注册和登录验证码，并管理用户和机器人。本文档把管理页面和服务器设置值集中整理在一处，供查阅。如果需要先安装，请参阅服务器安装。
打开管理页面
管理页面位于管理 HTTP 端口（运营配置中为 8080）的 /admin/，只能在服务器本机（127.0.0.1）上打开。运营方通过 SSH 隧道进入。
# 在自己的电脑上执行（保持运行）
ssh -N -L 8080:127.0.0.1:8080 <用户>@<服务器>
# 浏览器：http://localhost:8080/admin/
# 令牌（在服务器上查看）
sudo cat /srv/pabal/pabal_server/data/admin-token输入令牌后点打开（열기）。浏览器会记住令牌，可以用右上角的清除令牌（토큰 지우기）将其清除。如果要自行设定令牌，请设置 TELEGRAM_ADMIN_TOKEN（至少 16 个字符）——这样就不会写入文件。
各标签页显示的内容
| 标签页 | 内容 | 刷新 |
|---|---|---|
| 仪表盘（대시보드） | 当前在线的用户、会话和连接，用户、机器人、群组、消息和照片的数量，运行时间、端口、数据库，JVM，状态检查。测试号码开启时会显示警告横幅 | 5 秒 |
| 注册验证码（가입 코드） | 等待中的验证码（号码、发送方式、发送状态、验证码、剩余时间、输错次数）和最近记录。可以复制或取消验证码 | 3 秒 |
| 用户（사용자） | 所有账号——手机号码、登录邮箱（可编辑）、是否在线、登录设备数、消息数。退出所有设备（모든 기기 로그아웃）、封禁号码（번호 차단） | 10 秒 |
| 机器人（봇） | 用 BotFather 创建的机器人——创建者、命令菜单、连接方式（MTProto · HTTP 轮询 · Webhook 地址及失败原因）、等待中的更新数量 | 10 秒 |
| 设置（설정） | 注册和登录规则、短信、电子邮件（SMTP）、封禁手机号码 | 手动保存 |
| 存储（저장소） | 数据目录和数据库地址（密码会被隐藏）、照片数量和容量、按类型统计的存储流数量 | 10 秒 |
危险的操作（退出登录、封禁、取消验证码）需要点击两次才会执行。
注册和登录验证码
用户在应用中输入手机号码后，服务器会生成验证码，并通过在设置（설정）标签页中选定的方式发送出去。
| 发送方式 | 验证码的去向 | 应用界面 |
|---|---|---|
| 管理页面（관리 화면） | 注册验证码（가입 코드）标签页。由运营方复制后直接告知用户 | 号码 → “验证码已发送” → 验证码（新号码还要输入名字） |
| SMS | 通过 Twilio · Solapi · Webhook 之一发送短信 | 与管理页面方式相同 |
| 电子邮件（이메일） | 通过 SMTP 发送邮件 | 号码 → 输入电子邮件 → “验证码已发送到电子邮件” → 验证码 |
- 在电子邮件方式下，新注册可以使用任意地址，该地址会成为账号的登录邮箱（로그인 이메일）。已有账号只能通过已登记的登录邮箱接收——这是为了防止有人在别人的号码上填入自己的地址来登录。没有登录邮箱的已有账号，会改用短信（如已设置）或管理页面发送。可以在用户标签页中为其填入登录邮箱。
- 发送在后台进行，应用会直接进入输入验证码的界面。发送结果（成功或失败及原因）会显示在注册验证码标签页中。
- 注册（输入名字）只有在验证码输入正确之后才能进行。错误的验证码只接受允许的次数，超过之后，即使输入正确的验证码也会被拒绝。
设置——注册和登录
| 项目 | 含义 | 默认值 |
|---|---|---|
| 允许新注册（새 가입 허용） | 关闭后只有已有账号可以登录。新号码会以“号码无效”被拒绝 | 开启 |
| 验证码发送方式（코드 전달 방식） | 管理页面 / 短信 / 电子邮件 | 管理页面 |
| 在管理页面显示验证码（관리 화면에 코드 표시） | 在短信和电子邮件方式下，也在注册验证码标签页中显示验证码（以防发送失败） | 开启 |
| 测试号码 +99966…（테스트 번호） | 按服务器设置 / 开启 / 关闭。正式运营时请关闭 | 按服务器设置 |
| 验证码位数 · 有效时间（코드 자릿수 · 코드 유효 시간） | 5~6 位 · 1~60 分钟 | 5 位 · 5 分钟 |
| 重新请求间隔 · 每日上限（재요청 간격 · 번호당 하루 최대 요청） | 同一号码再次获取验证码前需等待的秒数（0~3600）· 24 小时内的最多次数（1~1000） | 60 秒 · 10 次 |
| 允许输错次数（틀린 입력 허용 횟수） | 超过后该验证码会被锁定（1~20） | 5 次 |
设置——SMS
| 服务商 | 要填写的值 | 备注 |
|---|---|---|
| Webhook（웹훅） | 接收地址（웹훅 주소，https://…）、Authorization 请求头（可选） | 服务器会发送 POST {"phone":"+8210…","code":"12345","text":"…"}。返回 2xx 即视为成功。适用于连接自建的短信服务器或其他服务 |
| Twilio | Account SID、Auth Token、发送号码（발신 번호）或 Messaging Service SID | 包括海外号码在内，覆盖全球 |
| Solapi（原 CoolSMS） | API Key、API Secret、发送号码 | 韩国国内短信。发送号码必须是在 Solapi 预先登记的号码。+82 号码会以 010… 的格式发送 |
文本（문구）中可以使用 {code}（验证码）和 {minutes}（有效时间）。默认值：[파발] 인증 코드: {code}（意为“[Pabal] 验证码：{code}”）。保存后，请用测试发送（테스트 발송）进行确认。
设置——电子邮件（SMTP）
| 服务 | 服务器 · 端口 · 安全（SMTP 서버 · 포트 · 보안） | 用户名 · 密码（사용자명 · 비밀번호） |
|---|---|---|
| Gmail | smtp.gmail.com · 587 · STARTTLS | Gmail 地址 · 应用专用密码（Google 账号 → 安全性 → 两步验证 → 应用专用密码） |
| Naver | smtp.naver.com · 587 · STARTTLS | 账号 ID · 密码（在邮件设置中开启 POP3/SMTP） |
| 公司内部邮件中继 | 中继地址 · 25 · 无（없음） | 留空 |
发件地址（보내는 주소）必须是该 SMTP 账号有权发送的地址。主题（제목）和正文（본문）中也可以使用 {code}、{minutes}。
用户管理
- 退出所有设备（모든 기기 로그아웃）：断开该账号的所有登录（授权密钥）。用于丢失了设备的用户。
- 封禁号码（번호 차단）：该号码将无法接收验证码，该号码的账号会立即在所有设备上退出登录。与设置标签页中的封禁手机号码（전화번호 차단）列表相同。
- 登录邮箱（로그인 이메일）：在电子邮件方式下，已有账号要通过电子邮件登录时需要它。
- @BotFather 是服务器内置的机器人，不能对它执行退出登录。
机器人管理
在机器人（봇）标签页中可以查看每个机器人的连接方式——是否通过 MTProto 连接，最近 1 分钟内是否通过 HTTP 调用过 getUpdates，Webhook 地址是什么以及当前是否正在失败（包括原因）。如果等待中的更新数持续增加，说明机器人程序已经停止，或者 Webhook 正在失败。删除机器人和重新签发令牌，由创建该机器人的人在 @BotFather 中操作。
环境变量
服务器先读取配置文件（server-config.json），然后用环境变量覆盖。运营用的 Compose 文件会设定下列值，因此通常只需修改 .env。
| 变量 | 含义 | 运营 Compose 中的值 |
|---|---|---|
TELEGRAM_PORT | MTProto 端口 | MTPROTO_PORT（8443） |
TELEGRAM_HOST | MTProto 监听的地址 | 0.0.0.0 |
TELEGRAM_PUBLIC_HOST | 告知应用的服务器地址（help.getConfig） | PUBLIC_IP |
TELEGRAM_WEB_PORT | 网站、文档、Bot API、管理页面的端口 | 8080 |
TELEGRAM_WEB_HOST | 该端口监听的地址。默认为 127.0.0.1 | 0.0.0.0（容器内。在主机上只以 127.0.0.1 公开） |
TELEGRAM_PUBLIC_URL | 网站地址。用于链接（me_url_prefix）、邀请链接、文档示例、预览图片 | https://DOMAIN/ |
TELEGRAM_DATA_DIR | 照片、admin-token、operations.json 的位置 | /app/data |
TELEGRAM_RSA_KEY | 服务器 RSA 私钥的路径（不存在时首次启动会生成，公钥为 .pub） | /app/keys/private.pem |
TELEGRAM_DC_ID | 这台服务器的 DC 编号 | （镜像默认值 1） |
TELEGRAM_DB_TYPE | memory · h2 · postgresql | postgresql |
TELEGRAM_DB_URL, TELEGRAM_DB_USERNAME, TELEGRAM_DB_PASSWORD | JDBC 连接 | jdbc:postgresql://pabal-postgres:5432/pabal, pabal, POSTGRES_PASSWORD |
TELEGRAM_DB_MAX_POOL_SIZE | 数据库连接数 | 20 |
TELEGRAM_ADMIN_TOKEN | 管理页面令牌（留空时在 data/admin-token 中生成） | ADMIN_TOKEN |
TELEGRAM_TEST_NUMBERS | +99966… 测试号码。仅限开发 | false |
TELEGRAM_WEBHOOK_ALLOW_LOCAL | 允许机器人 Webhook 使用 http:// 和内部地址。仅限开发 | （未设置 = false） |
JAVA_OPTS | JVM 选项（内存） | .env 中的值 |
数据文件
| 文件 | 内容 | 权限 |
|---|---|---|
keys/private.pem | 服务器 RSA 私钥。绝不外传 | 600 |
keys/private.pem.pub | 公钥。用于构建应用和 /docs/server-key.pem | — |
data/admin-token | 管理页面令牌 | 600 |
data/operations.json | 设置标签页中的值——注册规则、短信和 SMTP 的机密值、封禁的号码 | 600 |
data/media/ | 照片原图 | — |
PostgreSQL events 表 | 账号、对话、消息、登录、机器人、Webhook 设置——所有变更的记录 | — |
安全备忘
- 不要把管理端口直接开放到互联网上。运营配置中的 Caddy 会以 404 拦截
/admin、/health、/metrics等管理路径。 - 所有管理数据请求都需要
Authorization: Bearer <令牌>，其他网站的页面无法读取这些数据。 - 短信和 SMTP 的机密值只保存在
operations.json中，界面和 API 只会告知“已保存”。机密值输入框留空保存时，会保留原来的值。 - 令牌和机密值不会写入日志，日志中的手机号码会做遮盖处理。Bot API 地址（包含令牌）也不会写入日志。
- 授权密钥保存在数据库中，因此能够访问数据库的人就能解密用户流量。请像保护 RSA 密钥一样保护数据库和备份。
限制
- 等待中的验证码和最近记录保存在内存中，服务器重启后会丢失（在应用中重新请求即可）。
- 短信服务商的实际发送效果，需要用各服务商的账号来确认。服务器按照各服务商的文档来构造请求。
- 尚未提供的功能：删除账号、强制删除机器人、查看消息、查看日志、图表。