telesrv 配置参数手册

Status: operation. Scope: Configuration reference.

英文版：configuration.en.md

本文覆盖 internal/config 实际读取的全部配置。默认值和校验行为以 internal/config/config.go 为权威来源。所有配置修改都需要重启进程；telesrv 当前不支持配置热加载。

1. 加载方式、语法与优先级

• TELESRV_CONFIG 是选择 env 风格配置文件的进程环境变量。默认读取进程工作目录下的 .env；显式设为空可关闭文件加载。把它写在配置文件内部不会改变已选定的文件。
• 优先级为：非空进程环境变量 → 非空文件值 → 代码默认值。四个可空监听项 TELESRV_DEBUG_ADDR、TELESRV_BOT_API_ADDR、TELESRV_ADMIN_API_ADDR、TELESRV_PUBLIC_LINK_WEB_ADDR 允许用显式空的进程环境变量覆盖文件中的非空值，从而关闭监听。
• 文件支持空行、整行 # 注释、可选的 export 前缀和 KEY=VALUE；支持单引号、双引号。行尾 # 不会被当作内联注释剥离。
• 文件中的键必须以 TELESRV_ 开头，且只能包含大写 ASCII 字母、数字和下划线。语法合法但当前二进制未知的 TELESRV_* 键会被接受但忽略。
• bool 接受 1/true/TRUE/True/yes/on 和 0/false/FALSE/False/no/off；列表使用逗号分隔；时长使用 Go 格式，例如 200ms、30s、5m、168h。
• int、float、bool、duration 的非法文本会回退代码默认值；URL、app scheme、app name 以及登录邮箱依赖关系校验失败会阻止启动。
• 不要提交真实密码、token、私有 DSN 或 TURN secret。生产环境应使用受保护的 service environment 或密钥管理系统。

启动时若存在 <配置文件>.example，服务会以 INFO 报告模板中声明但配置文件和进程环境均未设置的键，以 WARN 报告配置文件中未被模板收录的键。报告只包含键名，不打印值、不写回文件；模板缺失时跳过这项提示性检查。

资料审核警告

用户 About 隐私隐藏整个字段，包含警告。用户本人、频道创建者及具备 ChangeInfo 权限的管理员读取用于编辑的原始描述。警告只存在于读投影，不落库，也不按匹配文字删除作者输入；客户端仍保留标记徽章。修改配置后需重启。

2. MTProto 监听、传输与资源预算

nested gzip admission 不新增环境变量。代码硬限制为：每个 gzip_packed envelope 输出最多 10 MiB；同一 transport frame 内 outer、nested、 sibling、失败尝试和 authoritative-profile re-decode 的累计解压工作最多 32 MiB。 live expanded buffer 释放后会归还进程内存，但不会返还该 frame 的 CPU/work counter； 保留的 typed graph 继续计入上面的 RPC scheduler 预算。

3. HTTP 端点、公开链接与管理后台

3.1 Bot API webhook 故障排查

先区分三个地址，禁止把 webhook 接收域名当成 Bot API 地址：

网络方向也不同：polling 是 bot 应用 -> telesrv Bot API，webhook 是 telesrv -> bot 应用 webhook receiver。因此 polling 正常只能证明前一条路径可达， 不能证明 webhook 的 DNS、出站 TCP、TLS、反向代理或 Docker hairpin 路径正常。

1. 从 Bot API 查询真实 webhook 状态

应在 bot 应用容器中使用它实际配置的 Bot API base URL；不要把 token 展开后粘贴到 聊天、工单或截图：

curl -sS -X POST \
  "${TELEGRAM_API_URL%/}/bot${BOT_TOKEN}/getWebhookInfo" | jq

若没有 TELEGRAM_API_URL 这个变量，就把它替换成与 TELESRV_BOT_API_ADDR 对应的客户端可达地址。例如 telesrv 监听 0.0.0.0:8088，同宿主 Docker 容器可能使用 http://172.17.0.1:8088；不要请求 http://0.0.0.0:8088。

按下表判读响应：

getWebhookInfo 查询的是 telesrv 持久化的交付事实；应用自己的 /health 只能证明 接收路由和 worker 已启动，不能代替这一步。

2. 用正确请求头验证接收端

Telegram webhook secret 与 Bot token、OIDC Client Secret、API key 都是不同凭据。 接收端校验的标准请求头是 X-Telegram-Bot-Api-Secret-Token，不是 Authorization: Bearer：

curl -i -X POST "${WEBHOOK_URL%/}${WEBHOOK_PATH}" \
  -H 'Content-Type: application/json' \
  -H "X-Telegram-Bot-Api-Secret-Token: ${WEBHOOK_SECRET_TOKEN}" \
  -d '{"update_id":2147483000}'

预期为 HTTP 2xx。401 invalid_secret_token 表示请求已经到达应用，但 header 缺失或 值不匹配。编辑 .env 后必须重建/重启读取该配置的应用；只修改磁盘文件不会更新 已经登记到 telesrv 的 secret，也不会更新接收进程启动时捕获的 secret。

3. 从 telesrv 的实际网络命名空间测试

浏览器或官方 Telegram 能访问公网 webhook，只能证明公网入站正常。必须从实际运行 telesrv 的宿主机、容器或 network namespace 再测一次：

docker exec <telesrv-container> sh -lc \
  'getent hosts bot.example.com; curl -vk --connect-timeout 10 https://bot.example.com/health/unified'

如果公网客户端正常而这里 dial tcp ...:443: i/o timeout，常见原因是同机公网 IP 回环失败。优先使用 split DNS 或容器 host mapping，让公网 hostname 在 telesrv 容器 内解析到反向代理的内部入口，同时保留原 hostname、HTTPS SNI 和证书校验。例如反代 的 443 已发布到 Docker 宿主机时，可先验证：

curl -vk --resolve bot.example.com:443:172.17.0.1 \
  https://bot.example.com/health/unified

验证通过后，可在 telesrv Compose 中使用与实际网络匹配的配置：

extra_hosts:
  - "bot.example.com:host-gateway"

其它可选修复包括：把 telesrv 接入反向代理所在 Docker network、为 Docker subnet 放行宿主机 443，或修正云安全组/NAT hairpin。telesrv 允许登记内部 HTTP receiver， 但只有在两端共享受控内网且调用方的 WEBHOOK_URL 不同时承担 OIDC、支付或公开媒体 回调时才应使用；不要为绕过网络问题盲目把应用的全局公开 URL 改成内部地址。

4. 修复后的闭环验证

1. 重新启动 bot 应用，让它用当前 URL、secret 和 allowed_updates 再次调用 setWebhook。
2. 发送一条新的 /start 或点击 callback 按钮。
3. 再次调用 getWebhookInfo；pending_update_count 应下降到 0，且不再出现新的 last_error_date。
4. 检查 telesrv Warning 日志中的 bot api webhook delivery failed。日志包含 bot_user_id、retry_in 和失败原因，但不得记录 webhook URL、Bot token 或 secret。
5. 检查接收应用是否记录并处理该 update_id。webhook 是 at-least-once，应用必须能 安全处理失败重试带来的重复 update。

若凭据曾出现在命令历史、聊天或截图中，立即轮换 Bot token、webhook secret、OIDC Client Secret 及同屏暴露的其它 API key/数据库密码；排查资料只保留脱敏结果。

3.2 Telegram Login / OIDC 完整启用流程

1. 一次性生成 data/telegram-login

在 telesrv 仓库根目录执行：

go run ./cmd/telegramloginkeygen -mode init -dir data/telegram-login
Get-ChildItem .\data\telegram-login

Linux 部署也可使用同一命令；生成后应限制目录权限：

go run ./cmd/telegramloginkeygen -mode init -dir data/telegram-login
chmod 0700 data/telegram-login
chmod 0600 data/telegram-login/*

初始化会生成以下私密文件，命令不会把密钥内容输出到终端，并会拒绝覆盖已经存在的 signing-keys.json、code-keys.json 或 client-secret-pepper：

• signing-keys.json 和三个 signing-*.pem：RS256、ES256、EdDSA ID token 签名私钥及清单；
• code-keys.json：一次性 authorization code 使用的 AES-256-GCM envelope key ring；
• client-secret-pepper：保存和校验 OIDC Client Secret 摘要时使用的 32 字节部署 pepper。

data/* 默认已被仓库 .gitignore 排除。不要把该目录放入 Git、发布压缩包、日志或 普通备份；多实例必须挂载同一份受保护的文件，并在轮换后一起重启。丢失 pepper 会让 现有 Client Secret 无法验证，丢失仍在发布窗口内的签名私钥会让尚未过期的 ID token 无法继续通过 JWKS 验证。

2. 配置并启动 Provider

以下示例直接通过 http://192.0.2.25:2401 对外提供 OIDC；请替换成客户端实际可达的 服务器 IP。直接监听局域网/公网网卡时使用 0.0.0.0:2401，仅由同机反向代理转发时 应改回 127.0.0.1:2401：

TELESRV_PUBLIC_BASE_URL=http://192.0.2.25:2401
TELESRV_PUBLIC_LINK_WEB_ADDR=0.0.0.0:2401
TELESRV_PUBLIC_APP_SCHEME=telesrv
# 多服务客户端可选：TELESRV_PUBLIC_APP_LINK_BASE=owpg://example.com

TELESRV_TELEGRAM_LOGIN_ENABLE=true
TELESRV_TELEGRAM_LOGIN_ISSUER=http://192.0.2.25:2401
TELESRV_TELEGRAM_LOGIN_ALLOW_HTTP=true
TELESRV_TELEGRAM_LOGIN_SIGNING_KEYS_FILE=data/telegram-login/signing-keys.json
TELESRV_TELEGRAM_LOGIN_CODE_KEYS_FILE=data/telegram-login/code-keys.json
TELESRV_TELEGRAM_LOGIN_SECRET_PEPPER_FILE=data/telegram-login/client-secret-pepper

使用 HTTPS 时，把 TELESRV_TELEGRAM_LOGIN_ISSUER 和公开根地址改成精确 HTTPS origin，并保持 TELESRV_TELEGRAM_LOGIN_ALLOW_HTTP=false。issuer 是 token 的 iss 以及 discovery 中所有端点的根地址，scheme、host 和 port 必须与依赖方访问的地址完全 一致。启动或重启 telesrv 后，先验证公开端点：

curl.exe http://192.0.2.25:2401/.well-known/openid-configuration
curl.exe http://192.0.2.25:2401/.well-known/jwks.json
curl.exe -I http://192.0.2.25:2401/js/telegram-login.js
curl.exe -I 'http://192.0.2.25:2401/js/telegram-widget.js?23'

discovery 返回的 issuer 必须等于配置值，authorization_endpoint、token_endpoint 和 jwks_uri 必须可从依赖方访问。使用反向代理时需原样转发 /.well-known/openid-configuration、/.well-known/jwks.json、/auth、/auth/status、 /token、/crossapp、/inapp、/telegram-login.js、/js/telegram-login.js、 /telegram-widget.js、/js/telegram-widget.js 以及 POST /telegram-widget/resolve。

3. 用本服 @BotFather 创建 OIDC Client

先用 /newbot 创建或选择已有 bot，然后在本服 @BotFather 中执行 /setlogin 并选择 该 bot。首次配置会返回：

• Client ID：bot user ID 的十进制字符串；
• Client Secret：只显示一次，与 Bot API token 不同，必须立即保存到密钥管理系统。

选择一次 bot 后会持续停留在它的配置会话中，无需为每项修改重复 /setlogin 和 bot username。可以逐条发送，也可以像下面这样在一条消息中粘贴多行命令（每条消息最多 32 行）。下面假设依赖方页面运行在 http://192.0.2.30:3000：

add origin http://192.0.2.30:3000
add redirect http://192.0.2.30:3000/oauth/callback
algorithm RS256
enable

全部修改成功后发送 /done，BotFather 会退出配置会话并返回最终配置摘要。各条修改会 立即生效；/cancel 只关闭当前会话，不会回滚已经成功的修改。多行消息若中途失败， BotFather 会明确列出已应用项、失败行以及未执行的后续行，并保留当前 bot 选择供修正 后继续操作。

origin 只能是无 path/query/fragment 的精确 Web origin，用于 JS SDK、popup CORS 和 legacy login_url；redirect 是 Authorization Code Flow 返回 code 的精确完整 URI。 不支持 wildcard 或 prefix 匹配。用 /logininfo 检查状态和登记值；用 /setlogin 增删 URL、切换签名算法或 disable；用 /resetloginsecret 轮换 Client Secret。可用的 签名算法为 RS256、ES256、EdDSA，以及仅在对应构建和 key ring 已提供时可选的 ES256K； EdDSA/ES256K 只允许 openid scope。

4. 依赖方接入标准 OIDC

依赖方应首先读取：

http://192.0.2.25:2401/.well-known/openid-configuration

标准流程为 Authorization Code + PKCE S256：

1. 生成随机 state、nonce 和 PKCE code_verifier，计算 S256 code_challenge；
2. 浏览器打开 discovery 中的 authorization_endpoint，携带 client_id、精确 redirect_uri、response_type=code、包含 openid 的 scope、state、nonce、 code_challenge 和 code_challenge_method=S256；
3. 用户在 TDesktop/Android 中确认后，依赖方 callback 校验 state 并取得一次性 code；
4. 服务端向 discovery 中的 token_endpoint POST grant_type=authorization_code、code、 同一 redirect_uri 和 code_verifier，机密 client 使用 HTTP Basic 或 client_secret_post 提交 Client Secret；
5. 用 discovery 的 jwks_uri 验证 ID token 签名，并严格校验 iss、aud、exp、 nonce 和非空 sub。不要只解码而不验签。

支持的 scope 为 openid、profile、phone、telegram:bot_access。当前不提供 UserInfo、refresh token 或 introspection endpoint。浏览器前端可以加载 <issuer>/js/telegram-login.js 使用本地 JS SDK；Client Secret 只能留在服务端。

已有前端若使用 Telegram 的 attribute-based Login Widget，只替换 widget script 的 来源；仅存在于 telesrv 的 bot 不得继续使用 https://telegram.org/js/telegram-widget.js：

<script async src="https://<telesrv-issuer>/js/telegram-widget.js?23"
  data-telegram-login="BotName"
  data-size="large"
  data-radius="10"
  data-request-access="write"
  data-lang="zh"
  data-onauth="onTelegramAuth(result)"></script>
<script>
  function onTelegramAuth(result) {
    // telesrv SDK 返回：{ id_token, user }，失败时为 { error }
  }
</script>

同时提供 data-client-id="<数字 bot user id>" 时优先使用该值；只有 data-telegram-login 时，shim 仅在本服 username 当前指向 bot、其 Login client 已 启用且浏览器精确 Origin 已为该 bot 登记时返回 client_id。data-size / data-radius 控制本地简单按钮，data-lang 透传给 Login SDK；data-request-access="write" 请求 openid profile telegram:bot_access，未设置时请求 openid profile。data-onauth 收到现有 telesrv SDK 的 {id_token, user}，不会伪造 Telegram 官方 widget payload。

Mini App 是独立接口，必须继续加载官方 https://telegram.org/js/telegram-web-app.js。telesrv 的 telegram-widget.js shim 不 替换该脚本，也不改变 Mini App 行为。

5. 使用 Bedolaga demo 验证完整链路

安装 demo 依赖：

python -m venv "$env:TEMP\telesrv-bedolaga-demo-venv"
& "$env:TEMP\telesrv-bedolaga-demo-venv\Scripts\python.exe" -m pip install `
  -r .\cmd\bots\bedolagaformat\requirements.txt

将第 3 步得到的 Client ID/Secret 和同一个 Bot API token 仅放入进程环境：

$env:TELESRV_BOT_TOKEN = "<bot_id>:<bot_api_secret>"
$env:TELESRV_BOT_API_SERVER = "http://192.0.2.25:8081"
$env:TELESRV_BOT_LOGIN_DEMO = "1"
$env:TELESRV_BOT_LOGIN_ISSUER = "http://192.0.2.25:2401"
$env:TELESRV_BOT_LOGIN_CLIENT_ID = "<BotFather 返回的 Client ID>"
$env:TELESRV_BOT_LOGIN_CLIENT_SECRET = "<只显示一次的 OIDC Client Secret>"
$env:TELESRV_BOT_LOGIN_PUBLIC_URL = "http://192.0.2.30:3000"
$env:TELESRV_BOT_LOGIN_LISTEN = "0.0.0.0:3000"

& "$env:TEMP\telesrv-bedolaga-demo-venv\Scripts\python.exe" `
  .\cmd\bots\bedolagaformat\demo.py --drop-pending --login-demo

确保 BotFather 登记的 origin 等于 TELESRV_BOT_LOGIN_PUBLIC_URL，redirect 等于 <TELESRV_BOT_LOGIN_PUBLIC_URL>/oauth/callback。在客户端向 bot 发送 /logindemo：第一颗 按钮验证 Bot API login_url 和 HMAC 回调，第二颗按钮页面分别验证本地 JS SDK popup 以及 Authorization Code + PKCE/JWKS。省略 Client Secret 时只能验证 JS popup，服务端 code flow 会明确禁用。

6. 密钥轮换

签名 key 轮换时，旧公钥发布窗口必须至少覆盖配置的 ID token TTL 再加 10 分钟；操作 完成后所有实例一起重启：

go run ./cmd/telegramloginkeygen -mode rotate-signing -algorithm RS256 `
  -id-token-ttl 1h -publish-for 2h -dir data/telegram-login
go run ./cmd/telegramloginkeygen -mode rotate-code -dir data/telegram-login

rotate-signing 可分别用于 RS256、ES256、EdDSA；rotate-code 保留旧 code key 并新增 active key。不要手工编辑 manifest 或 PEM，不要在各实例上分别生成不一致的 key ring。

4. PostgreSQL、Redis、文件与 seed

语言包 seed 以文件 manifest 为事实源。新增语言时放入 data/langpack/<pack>/<pack>_<lang>_v<version>.strings 并重启 telesrv；pack 必须与所在一级目录一致，允许 Telegram 已使用的字母、数字、- 与 _（例如 android_x），lang 会统一为小写、连字符形式（例如 pt_BR 归一为 pt-br）。同一语言存在多个文件时只读取最高版本。修改已有语言的有效内容必须提高版本；同版本有效内容变化或版本倒退会阻止启动。删除语言文件或整个 pack 子目录后，下次重启会原子移除对应数据库目录和字符串。启动先流式计算源文件 SHA-256；未变化文件复用上次原子 manifest，不解析字符串也不写库，只有新增或变化文件才解析并通过 PostgreSQL COPY 整包替换。

对象存储保持单后端运行。在显式离线迁移完成对象复制、size/SHA-256 校验并更新 file_blobs.backend 之前，不得直接翻转 TELESRV_BLOB_BACKEND。

5. 登录、OTP Provider、SMTP 与 passkey

6. 地图、外链媒体、链接预览与上传

7. AI compose 与 Business automation

聊天翻译会把用户主动选择翻译的消息正文发送给所配置的外部 provider。默认日志不记录正文，但部署者仍应在隐私政策中披露上游处理方；只配置 local 时服务端返回 TRANSLATIONS_DISABLED，不会回原文冒充译文。

对 TELESRV_AI_PROVIDERS 中的每个名称，telesrv 会转大写并把非字母数字字符替换为 _，再读取下列动态参数。例如 openai-compatible 对应 suffix OPENAI_COMPATIBLE。

下列 fallback 只支持进程环境变量，因为 env 文件会拒绝不以 TELESRV_ 开头的键：OPENAI_API_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY。显式 TELESRV_AI_<NAME>_API_KEY 优先级更高。

8. Read-model 与 auth-key 缓存

9. Outbox、推送、限流、retention 与 GC

10. Premium 与 Stars 开发赠送

本地账号评分与 collectible username

账号评分是 gramsrv 自己的本地风控/信誉复合分，组合 Stars 收支、账号活跃和管理处罚；它不承诺 1:1 复刻 Telegram 的私有评分算法。已计算的本地等级会投影到 userFull.stars_rating，本人还会收到 stars_my_pending_rating 与生效时间，让官方客户端直接显示；他人的 pending 永不下发。资料页只读取后台 worker 已持久化的评分并复用现有 30 分钟 userFull 投影缓存，不会同步重算或写库。Collectible username 由管理员签发，本功能不访问外部市场、钱包或区块链节点。

等级为 0..100（分数低于 25 为 0 级），100 是本服为 stars_rating 选择的本地策略上限，TL 整数字段本身没有这一限制；n 级需要 25 * n² 分（平方增长，前期升级快、后期有分量）。100 级需要 250k 分，与旧 50 级阶梯的封顶分相同，因此 20261013010000_rating_level_scale 迁移把已存的分数整体映射到更细的刻度（旧 n 级 → 新 2n 或 2n+1 级；恰好落在旧阈值上的分数映射为 2n 级），不会等到下次重算才生效。到达 100 级后不再下发 next_level_stars，客户端据此显示满级标记而不是进度条。

fragment.collectibleInfo.amount 与 crypto_amount 使用币种最小单位：例如 USD 1000 表示 10 美元，TON 900 表示 900 nanotons，XTR 无子单位。后台 UI 负责整币单位与最小单位转换；直接调用 Admin API 的集成必须自行传最小单位。

官方平台认证

官方认证对应 user.verified / channel.verified。申请由内置 @verifybot 收集、管理后台审核；提交和批准时都会重新校验目标存在、公开 username、申请者控制权、账号状态与系统账号禁入，badge 写入和决定状态在同一事务提交。申请 URL 只做 public http(s) 形状校验，服务端不会抓取，避免 SSRF。

第三方 bot 认证

第三方认证对应 botVerification，由管理员授权的 verifier bot 使用自己的 custom emoji document 与描述标记 user/channel，不会授予官方 checkmark。Icon 必须是客户端可通过 messages.getCustomEmojiDocuments 读取的真实 document。每个 peer 只保留一个 wire-visible mark；新的 verifier 替换旧 mark，禁止旧 badge 在撤销或 kill switch 后意外复活。客户端自定义描述上限通过 appConfig bot_verification_description_length_limit=70 发布。

11. 私聊通话、群通话、TURN、SFU 与直播

12. 生产部署最低检查清单

生产至少应显式检查并替换这些开发值：PostgreSQL DSN 与 TLS、Redis 密码和网络暴露、RSA 私钥持久化、固定开发验证码暴露、Admin 凭证/session key、OTP Webhook/SMTP secret、AI/Mapbox API key、TURN secret 与防火墙端口、公开 URL/scheme 与客户端一致性，以及真机所需的非 loopback SFU/TURN advertise IP。

Cross-collection gift crafting

TELESRV_STAR_GIFT_CROSS_CRAFT_USER_IDS is an explicit comma-separated positive user-ID allowlist; empty disables AI cross-collection crafting. A configured AI provider and blob backend are required. Ordinary same-collection catalog crafting remains available.

可选钱包与充值能力

TELESRV_WALLET_STATE_DIR 默认留空，关闭钱包。显式配置 POSIX 0700 私有目录后 启用 Layer 230 部分钱包接口；Docker 应使用 /var/lib/telesrv/wallet。 TELESRV_WALLET_KEY_FILE 默认为 data/wallet/keys.key，Docker 默认位于同一持久 卷的 wallet/keys.key。主密钥与完整账号状态必须共同备份；首次生成 0600 文件， 重启校验已有密文与配置密钥一致，不推断没有存量证据的 raw-key 编码。 可选 TELESRV_WALLET_TONCENTER_API_KEY 要求已配置目录；留空不访问外部 TON。

TELESRV_WALLET_INTERNAL_TRANSFERS=false 默认关闭，只控制本部署内部 Gram 账本的用户间转账。 启用时必须配置钱包目录并使用兼容客户端；它不启用 TON 链上发送或 gasless。 还必须设置 TELESRV_STARGIFT_TON_STARTING_GRANT=0；启动校验与扣款存储均拒绝非零初始赠款，防止注册多个账号集中免费余额。 关闭赠款不追溯删除已有余额，运维启用转账前须审核历史赠款。 每笔转账必须通过账号 2FA 的 SRP 校验取得 account.getTmpPassword，授权在同一资金事务中一次性消耗。 授权必须属于当前登录及密码版本，未过期且签发不超过 120 秒；无 2FA 的账号须先设置密码。 wallet.sendTransfer.data_normal 使用版本 1 JSON：version、recipient_user_id、random_id、 amount_nanoton、可选 comment 和 Base64 编码的 32 字节 tmp_password。收款人和随机 ID 必须与 RPC 一致。 相同请求重试返回原回执，旧 JSON、所有 TON BOC 和 gasless 请求均拒绝。地址查询不创建其他用户的钱包。 收款人更换绑定钱包不影响相同请求重放；相同 random_id 携带不同授权或内容返回 RANDOM_ID_DUPLICATE。 发送方回执使用发送方负数流水的 ID。收款人拉黑发送方时，转账与私聊回执均拒绝。 其他非联系人消息隐私与付费消息规则尚未应用于此扩展回执，扩大部署前需单独确定该策略。 help 服务按配置发布扩展能力，保留运维显式 app-config；丢失的余额推送由 wallet.getState 恢复。 本扩展的 upstream 接纳仍需维护者明确决定，部署启用不代表维护者批准。 余额/流水来自本服 nanoton 账本，不代表链上到账；链上发送、gasless、备份/导出和 TON Connect 会话尚未实现，开启目录不等于开启这些能力。

TELESRV_DONATIONS_ENABLED=false 默认禁止生成 donations 助记词和启动链监听。 已有使用该功能的部署升级前须显式设为 true 并启用/配置所需链。donations 加密密钥 与钱包主密钥是不同文件。新纯数据迁移关闭空/种子占位 RPC 链，保留已配置远端链。 关闭总开关不删除已存在的钱包、地址或充值记录。