# Telegram · 连接、代理和数据保护

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/connection/

身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

身份验证、自动代理池、IP 模式、备用策略、外部请求及密钥存储。

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/)

![部署与恢复](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f)

本文档描述了 TgWitness 0.9.3 的行为及其限制。身份验证、 源访问、网络连接和捕获完整性是独立的状态。 有关登录步骤、文件格式和多账户信息，请先参阅 [账户和会话格式](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/)。有关事件策略和重启 行为，请[参阅采集原理](https://phishdestroy.io/tgwitness/zh/docs/reference/collection/)。

## 连接设置指南

在**更多工具→账户→连接路径**中，管理员可选择**此账户**、**账户 组**或**所有账户**，然后选择一条路径。**查看选择**会列出 受影响的账户。**准备并检查**功能可在不更改 已保存路径的情况下测试建议的路径。**应用已检查的连接**会验证预览结果，在 必要时暂停监控，保存路径并恢复已运行的监控。 系统绝不会在先前处于空闲状态的账户中启动数据采集。历史数据下载将保持 暂停状态，并可单独恢复。切换前请暂停正在进行的导出操作。

群组更改默认会为每个账户保留其独立路径。仅当预览列表中显示了您期望的更改时， 才应清除该选项。 应用程序会报告每个 账户的结果；这并非跨数据库的“全有或全无”式操作。若 切换失败，该账户将恢复之前的设置。恢复失败的情况会 明确显示。预览有效期为十分钟，且连接 设置或群组成员资格的更改需要重新检查。

当“Apply”的路线、 模式和策略保持不变时，它会将成功的预检结果重复使用，有效时长最长为90秒。受管隧道仍必须保持相同的运行 进程。较早的检查结果、已更改的隧道进程以及自动MTProxy池路线 将重新进行检查。签名的应用程序记录会保留原始检查时间， 并记录重复使用情况及其有效期。每次预检都会关闭其临时未认证的 客户端；收集器则使用其自身的授权会话进行连接。

| 路径 | TgWitness 管理的内容 |
| --- | --- |
| 直接 | 来自主机的连接；未检测到外部主机 VPN，也未强制执行。 |
| VPN | 每个账户仅有一个全隧道 WireGuard 配置文件，由本地用户空间中的 SOCKS5 进程承载。不安装任何主机接口或驱动程序。 |
| 我的代理 | SOCKS5、HTTP CONNECT 或 MTProxy 凭据。SOCKS5/HTTP 字段可填写 URL。选择多个账户时，将共享此处输入的代理。 |
| 公开版 MTProto | 现有池分配Telegram路由。在高级设置中配置单独的合适代理之前，外部请求将被禁用。 |
| WARP | 为每个选定的账户建立独立的本地隧道，并将 WARP 注册信息和 WireGuard 配置文件保存在该账户的保险库中。 |

当前路由检查使用的是一个全新的、未经身份验证的 Telegram 传输通道，而非 该账户的会话。它通过该路由向 该账户的数据中心建立传输连接，并进行一次未经身份验证的 MTProto 往返通信 （`req_pq_multi`）；该过程不会生成授权密钥，也不使用任何账户。 报告的延迟值等于连接时间加上往返时间，且该检查 会分别记录这两部分。对于支持 HTTP 的路由，它还会请求 通过该路由对 Cloudflare 的 HTTPS 追踪进行请求，并显示其报告的出口 IP、 国家/地区、WARP 状态和检查时间。除非追踪 报告 WARP 处于活动状态，否则 WARP 准备将失败。这些预检会报告路由连通性及 观察到的出口。请通过存档的采集和 验证结果审查捕获的记录。仅凭本地进程正在运行并不代表出口检查成功。

该面板会计算最近五次检查的移动平均值。当 该平均值超过5秒，或者连续三次检查超过该值时，该路由即被视为**速度较慢**； 若连续两次检查失败，则该路由被视为**不可用**； `network.slow_route` 并 `network.route_recovered` 记录这些变化。对于速度较慢的WARP路由**，“重新掷骰WARP**” 会重启该账户与其他Cloudflare WARP端点之间的隧道连接，保留 最快的连接，并记录 `network.warp_rerolled` 并记录其前后时间； **“新 WARP 身份**”会注册一个新的 WARP 设备，并仅在该设备 速度更快时保留它。本地代理地址、Telegram 账户及其会话保持 不变；Telegram 连接将通过重启后的隧道重新建立。速度较慢的 WARP 路由最多每 30 分钟自动重启一次；若此举 无效，后续重启将等待操作员处理。

### 便携版 WARP 和 WireGuard

这是一个 **非官方的 WARP 集成**，使用 [wgcf 2.3.1](https://github.com/ViRb3/wgcf/releases/tag/v2.3.1) 和 [wireproxy 1.1.3](https://github.com/windtf/wireproxy/releases/tag/v1.1.3)。 管理员需在首次下载或 WARP 注册之前明确接受该设置。 这些设置连接会直接连接到 GitHub 和 Cloudflare，并 泄露设备的 IP 地址。普通账户的流量在应用该设置前 仍保持原有路由。Cloudflare 会选择出口地址和国家；不同的隧道 可以共享同一个出口地址。该功能不提供国家选择、周期性 IP 轮换以及全主机范围的 VPN 杀开关功能。

支持下载的辅助程序：Linux 和 macOS x86-64/ARM64，以及 Windows x86-64。 会根据已审核源代码中捆绑的 SHA-256 哈希值对构建产物进行校验， 并在启动前再次对缓存的可执行文件进行校验。 任何辅助程序均不会被添加到 PATH 环境变量中，也不会作为系统服务安装，或配置为公开监听器。所有文件均位于 工作区下的 `portable-routes/` 目录中，并存储在加密的保险库条目内。 环回监听器 SOCKS5 需要独立生成的凭据。

私有配置文件和 WARP 账户凭据使用现有的 工作区保险库进行加密。运行期间，辅助程序需要一份仅所有者可见的明文配置文件； 正常停止时该文件会被删除。主机崩溃可能会导致该文件残留在 仅所有者可见的数据文件夹中。这不会对磁盘进行加密，也无法防止 管理员访问。 如果面板的父管道 消失，监督程序将关闭隧道。失败的隧道绝不会启用直接回退。面板重启 将恢复选定的隧道；启动失败时，将在限定延迟后重试。**停止 隧道** 也会暂停监视并保持已停止状态。**启动隧道** 启动隧道；准备就绪后需单独恢复监视。

上传的 WireGuard 配置文件必须包含一个接口和一个对等节点、完整的 IPv4 和 IPv6 路由，且不得包含钩子、包含语句、环境变量替换或额外的 监听器。公共端点地址将在启动前解析并固定。 请使用外部 VPN 或 SOCKS5 网关来连接 OpenVPN/IPsec 及私有端点。

## 认证方法

**API ID 和 API 哈希用于标识应用程序；它们不能替代账户登录。** 在 TgWitness 中，它们是可选的。优先级顺序为：表单中输入的一组，然后是来自 导入的账户 JSON 文件中的一组，接着是保存在工作区中的一组，最后是内置的 50 个 对，当Telegram拒绝某组时，系统将按随机顺序尝试并自动轮换。只有 Telegram Desktop密钥对（2040）会随匹配的Telegram Desktop客户端描述一同发送。 您可在[my.telegram.](https://my.telegram.org) org的API开发工具中生成的自有密钥对可用于所有账户；每个账户仍拥有独立的授权。

| 方法 | 要求 | TgWitness 支持 |
| --- | --- | --- |
| 手机号、代码、可选的双因素认证 | 账户访问；API 对（可选） | 面板登录 |
| 认证密钥 HEX + DC ID | 完整的 512 个字符密钥和 DC 1–5 | “直接**授权密钥**”选项卡；在保存授权前，可选的“用户 ID”字段需先进行验证 |
| Telethon StringSession | 一个有效的会话字符串 | 面板登录 |
| Telethon SQLite `.session` | 封闭式、连贯的文案 | 支持直接导入 7/8 版本的模式；可选离线命令行界面 (CLI) |
| Pyrogram SQLite `.session` | 已关闭的生产环境用户会话 | 直接通过面板导入模式 2/3 |
| Telegram 桌面版 TData ZIP | 一个现代账户；若设有保护，则需输入本地密码 | 带校验和/解密校验的内存内转换 |
| 账户 JSON | 支持的 API/会话/密钥字段 | 仅凭元数据即可自动填充 API 凭据；但仍需通过会话/密钥或手机/二维码登录 |
| 二维码登录 | 来自授权 Telegram 应用的确认 | 本地 QR 码生成、过期/重试功能，可选双因素认证 |
| TDLib / Pyrogram StringSession | 其他特定于库的格式 | 不支持 |
| 机器人令牌 | 一个拥有独立访问/更新模型的机器人 | 此收集器未使用该工具 |

Telegram 负责选择代码交付方式，包括是否发送短信。API 哈希无法修复 已被撤销的会话，也无法替换遗忘的 2FA 密码。TgWitness 不会将 登录码或 Telegram 2FA 密码持久化到磁盘上。

对于私有源，该账户必须已具备访问权限。无需提供群组用户名。 代理或会话导入既不授予成员资格，也不授予管理员 权限。成员能否查看加入群组之前的聊天记录，由聊天设置决定。

## 导入 Telethon 会话文件

Telethon SQLite、Pyrogram SQLite 和 Telegram Desktop TData 采用不同的格式。 该面板会检测并转换受支持的结构；重命名文件并不属于 转换操作。在**文件**下选择一个会话及其对应的 JSON 文件，点击**检查文件**，然后**点击连接账户**。最多接受四个匹配的文件， 总大小不超过 8 MiB。 有关 TData/JSON 的详细信息，请参阅[格式限制](https://phishdestroy.io/tgwitness/zh/docs/reference/accounts/)。 不提供密码恢复功能。通过手机/双因素认证或二维码登录将创建独立的授权。

仅限 Telethon 的可选命令行路径仍然可用：

1. 停止客户端使用原始会话，并制作一份一致的副本。该 转换器会拒绝包含未完成 WAL/日志的文件。请正确关闭原始 客户端，而非通过删除这些文件来绕过检查。
2. 在 TgWitness 环境中，运行：

```
python -m tgwitness.sessions account.session --out account.tgwitness-session
```

1. 在**“添加账户”→“文件**”下，加载结果或 粘贴其字符串，然后继续。
2. 请核对显示的数字账户 ID，选择数据源并开始监控。

**转换后的文件是一个未加密的账户访问密钥。** 请将其保存在受保护的 存储位置，切勿将其提交或发送给第三方转换服务。TgWitness 会将其授权会话保存在加密保险库中。复制会话不会 创建单独的授权：请勿使用克隆的授权密钥运行多个客户端， 并假设它们能独立接收更新。

转换操作仅传递授权，而非原始消息、实体缓存或 持久化更新游标。它无法解决进程重启后的更新恢复问题。

## MTProto、Telethon 和代理服务器

MTProto 是 Telegram 的协议。Telethon 是 TgWitness 使用的 Python 客户端库。 MTProxy 是一个 Telegram 传输代理；SOCKS5 和 HTTP CONNECT 提供通用 隧道。这些均无法替代账户身份验证。

请在 **更多工具 → 账户 → 设置 → 连接设置 → 更改连接路径** 在 登录之前。新工作区默认设置为 **自动 MTProxy · 公共列表** with **隐藏地址**. 已显式使用直接模式的现有工作区将保留允许该模式的设置。

文件的读取是通过与读取消息不同的独立连接进行的，这与官方 应用的做法一致。在该账户所属的数据中心内，系统会复用该账户的授权密钥并 建立新的 MTProto 会话；对于其他数据中心，则在 账户连接期间生成并授权一个密钥，且该密钥仅保存在内存中。每个文件连接都使用与该账户相同的 路由。每个数据中心中的文件连接数量受**“参数 → 性能 → “每个 Telegram 数据中心的文件连接数”所限制**；若设置为 0，则仅通过账户的主 连接读取文件。同一安装环境下的所有账户 最多可同时建立五个 Telegram 连接。

## IP 模式

路由决定连接方式。面板中“账户” 部分的 IP 模式和 **IP 保护**功能，决定了服务器地址何时可能被暴露。这些控制功能不会 安装 VPN，也不会将设备的所有流量都通过该路由传输。

| 模式 | Telegram | 外部请求 |
| --- | --- | --- |
| 隐藏地址（`hide`) | 请使用代理；若均无法连接，请稍候。无直接备用方案。 | 要求使用 SOCKS5/HTTP；拒绝未通过适用代理的请求。 |
| 直接操作仅作为最后手段（`fallback`) | 自动 MTProxy 可能会在配置的延迟时间过后使用 Direct，随后恢复使用正常工作的代理。 | 建议使用已配置的外部代理或该账户的 SOCKS5/HTTP 路由；否则允许使用“Direct”模式。 |
| 服务器位于隧道或 VPN 之后（`tunnel`) | 允许使用直连路径，并支持即时自动切换至备用池。 | 若未配置相应的代理服务器，则允许直接连接。 |

隧道或 VPN 模式假设您单独管理该网络。如果没有可用的 隧道，目标端将能看到服务器本身的地址。请根据 您的实际网络环境选择模式，而非仅依据选项名称。

### 选择路径

| 路径 | 设置 | 边界 |
| --- | --- | --- |
| 自动 MTProxy | 内置列表或运算符目录 | 维护一条可用的 Telegram 路由；直接备用方案取决于 IP 模式 |
| 直接 | 隧道或 VPN 模式 | Telethon 使用主机的网络路由 |
| SOCKS5 | 主机、端口、可选的用户名/密码 | python-socks，已启用远程目标 DNS 功能 |
| HTTP CONNECT | 主机、端口、可选的用户名/密码 | 仅支持纯 HTTP CONNECT；尚未实现与代理服务器本身的 TLS 连接 |
| MTProxy | 主机、端口、密钥 | 实验性 Telethon 传输协议；32 位十六进制数字或 `dd` + 32 位十六进制数字 |

虚假 TLS `ee` 密钥将被拒绝。Telethon 1.45 的规范化处理可去除前缀 和域名，但这并不实现虚假 TLS 功能。请粘贴 `tg://proxy?server=…&port=…&secret=…` 或 `https://t.me/proxy?server=…&port=…&secret=…`，并选择**“从链接填充字段**”。 这将在不建立连接或保存的情况下验证并填充字段；请单独审查并保存 路由。手动字段仍可使用。参见 [Telegram 代理链接](https://core.telegram.org/api/links#proxy-links)。

### 由您的安装环境提供的公共代理

该内置列表整合了七个来源： [SoliSpirit/mtproto](https://github.com/SoliSpirit/mtproto)、 [zakky8/mtproto-proxy-pro](https://github.com/zakky8/mtproto-proxy-pro)、 [kort0881/telegram-proxy-collector](https://github.com/kort0881/telegram-proxy-collector)、 [3yed-61/MTP-Collector](https://github.com/3yed-61/MTP-Collector)、 [Therealwh/MTPproxyLIST](https://github.com/Therealwh/MTPproxyLIST)、 [KhodeJav/telegram-proxy-collector](https://github.com/KhodeJav/telegram-proxy-collector) 以及 [tgmtproxy/telegram-mtproto-proxy-list](https://github.com/tgmtproxy/telegram-mtproto-proxy-list)。 该打包快照包含端点信息、来源归属及下载日期。 列表仅作为输入；下文的连通性检查将决定使用哪些代理。

**自动 MTProxy** 会检查 Telegram 传输连接状态，维持一个可用的代理， 并在代理失败时切换至另一个。当有足够多的 可用条目时，工作区会优先选择不同的代理；代理可以共享出口地址。失败的代理 会在再次尝试前进入休眠状态。如果所有代理均不可用，IP 模式将决定收集操作 是必须等待还是可以使用直接连接。 更换代理不会更改账户 也不会清除其日志。路由选择和变更都会记录在签名日志中。

当自动路由处于活动状态时，列表每小时刷新一次，传输检查默认 每十分钟运行一次。这些间隔时间均可配置。**更新公共列表** 会触发刷新；仅查看列表不会更改已保存的手动路由。

**Telegram 流量和 HTTPS 请求使用不同的路由。**列表下载使用 独立的 HTTPS 连接以及提供的外部请求路由。 `TGWITNESS_PROXY_FEED_PROXY` 会通过 HTTP/SOCKS5 代理显式覆盖该路由； 两种 Compose 收集器变体均会转发该路由。后台池遵循主工作区。 不会向数据源提供商发送任何 Telegram 会话、API 凭据、控制面板令牌或机器人令牌。 提供商名称、快照日期和下载路径会显示在**“列表来源”部分**。

MTProxy仅承载Telegram流量。工作区的HTTP操作（如时间戳、 通知、站外副本和源代码验证）在 已配置时会使用独立的SOCKS5/HTTP代理，否则则使用该账户的SOCKS5/HTTP路由。若两者均未配置，"隐藏地址"功能将拒绝 该请求；其他模式则允许"直接"连接。外部请求可被禁用。显式 配置的订阅源下载代理仍由操作员单独覆盖。 独立的见证服务保持其自身的路由。

对于由操作员管理的私有服务，现有的服务器环境设置 `TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1` 允许私有目标，并保持 代理端的主机名解析。该设置无法通过控制面板启用。仅限公共 模式会在查询公共解析器之前拒绝 `.onion` 目标；Tor 洋葱 服务需要明确的私有目标设置以及合适的代理。 此 DNS 行为适用于外部 HTTP 操作，不适用于 Telegram 的传输协议。 Cloudflare 提供了关于 [JSON DNS 端点的](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/)文档。

****自动池参数****

在**更多工具→参数→自动 MTProxy**下，配置故障阈值、冷却时间、 计划轮换、代理共享和允许的备用延迟。

| 控制 | 默认 |
| --- | --- |
| 替换前断开连接 | 3 项，耗时 10 分钟 |
| 每次连接尝试中尝试的代理数量 | 3 |
| 首次 / 故障后最大恢复时间 | 10分钟 / 6小时 |
| 计划轮换 | 已禁用；失败时启用 |
| 每个代理的账户数量 | 0：优先单独条目，必要时合并。设置为 1 以等待独占条目。 |
| 允许直接回退前的延迟时间 | 10分钟；隐藏地址仍被直接拒绝 |
| 数据源刷新/传输检查 | 60 / 10 分钟；主工作区值适用于共享池 |

不同的代理可以共享一个出口地址。Telegram 的限制适用于每条路由。

若要用您自己的运营商目录替换公共列表，请配置以下覆盖设置。 这将完全禁用外部订阅，包括当其 `proxies` 数组为空时。

[将空目录](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proxies.config.example) 复制到 `proxy-config/proxies.json` ，并添加您已部署的公共端点：

```
{"format": "tgwitness-proxy-catalog-v1", "proxies": [
  {"id": "project-eu", "label": "Project EU",
   "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}
```

必须替换示例值。最多接受 32 个不同的条目。 经过身份验证的列表会返回标签/主机/端口，无需共享密钥；选择其中一个 会将其凭据保存到工作区保险库中。在进行 明确的传输测试之前，可用性尚未经过测试。如果目录格式不正确，则可进行手动配置。

本地运行：将 `TGWITNESS_PROXY_CATALOG` 设置为本地 JSON 路径。Docker：

```
docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build
```

该覆盖层以只读方式挂载 `proxy-config`；文件必须可被容器 UID 10001 读取。 该目录被排除在 Git、Docker 构建上下文和源代码归档之外。此 目录用于配置收集账户；[Witness 机器人](https://phishdestroy.io/tgwitness/zh/docs/reference/witness/)使用其自身的 HTTP/SOCKS5 路由，而非 MTProxy。

直接备用方案由上文所述的 IP 模式决定。在 更改路由前请暂停监控。保存操作将断开旧客户端的连接并取消未完成的登录；新 客户端将使用已保存的路由。该账户的日志/会话绑定关系保持不变。 设置将覆盖之前的路由：编辑时请重新输入代理凭据。

凭据采用`network.enc`加密。API不会返回用户名、 密码或密钥。签名记录包含路由类型以及凭据 是否存在，但不包含端点和密钥。操作员可在控制面板中查看端点。 密钥字段在保存、锁定或切换工作区后将被清空。

**测试 Telegram 连接**（登录前也可使用），通过该路径建立并关闭一个临时 未经授权的 Telegram 连接。该操作不会联系任何 IP 检测 网站。测试成功仅表示传输连接已建立，并不代表群组访问权限、消息 完整送达或匿名性。

该代理适用于 Telegram 客户端的连接，包括 Telegram 数据中心（DC）的媒体 下载。浏览器、pip、SSH 以及手动调用的 TSA 工具则采用独立路径。 代理主机名可在本地解析。`rdns` 影响目标主机名； Telegram 通常提供数据中心（DC）的数值 IP 地址。

SOCKS5 和普通 HTTP CONNECT 本身不会对代理凭据或 客户端到代理的隧道进行加密。MTProto 会单独保护 Telegram 流量。在不可信网络上，请使用 适当的安全通道连接到代理。私人群组 是传输过程中受 MTProto 保护的云聊天；端到端秘密聊天是一种独立的聊天 类型，由[秘密聊天模块](https://phishdestroy.io/tgwitness/zh/docs/reference/secret-chats/)进行记录。

## 加密与签名

| 层级 | 已实现 | 操作员责任 |
| --- | --- | --- |
| Telegram 流量 | Telethon MTProto | 平台可信度、传输路径及可用性 |
| Web 控制面板 | 持有人令牌、默认回环设置、请求限制 | 通过 HTTPS 或 SSH 隧道进行远程访问 |
| 秘密 | Fernet 用于管理 API 凭据、会话、代理凭据及签名私钥 | 保护解密密钥和运行主机 |
| 保险库密钥 | 新安装时使用本地密钥或外部主密钥 | 独立的受保护存储空间和密钥备份 |
| 消息和附件 | 明文应用程序存储 | 加密磁盘/卷 |
| ZIP/JSONL/CSV/HTML | 完整性校验，不进行内容加密 | 保护导出的副本和传输内容 |
| 来源与时间 | 签名日志、流程收据、RFC 3161 工具 | 可信密钥、独立检查点/TSA 及保管流程 |

“账户”中的**存储保护功能**会显示这些状态。面板令牌是一种 访问密钥，而非加密密码。它授予管理员访问权限； [已签发的令牌](https://phishdestroy.io/tgwitness/zh/docs/reference/access/)可限定在特定账户和聊天群组范围内。工作区共享 主机进程，并非独立的租户。

BitLocker、LUKS、FileVault 或受管加密卷可在 各自的威胁模型下保护存储数据。 已解锁且正在运行的机器的管理员 仍然可以读取数据。在存储规划中应将 SQLite WAL/SHM、媒体文件、临时导出文件、交换文件、备份 以及浏览器下载内容纳入考虑范围。Docker 卷仅因其 是卷这一事实，并不意味着它已被加密。

## 外部主密钥

对于新安装，请将主密钥放置在数据目录之外。 此操作不会自动迁移现有的本地密钥库。请准备一个 仅服务身份可访问的密钥目录，然后运行：

```
python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case
```

PowerShell，使用已安装的项目环境：

```
python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case
```

在 Docker 中，将文件以只读方式挂载到 `/data` 之外（例如 `/run/secrets/tgwitness-master.key`），并将环境变量设置为该路径。 该服务的 UID 必须具备读取权限。请通过 环境/配置文件传递路径，而非密钥字节。

每个工作区都会获得一个随机的公共盐值，以及通过 HKDF-SHA256 派生出的专属 Fernet 密钥。`vault.external.json` 仅存储派生元数据，而非主密钥。 若密钥缺失或错误，系统将无法启动，且不会在后台自动替换密钥。请同时保留 盐值元数据和主密钥以备恢复之用。

所有工作区均源自同一主密钥；若主密钥遭泄露，将影响整个 安装环境。运行中的进程可解密机密信息。本工具并非硬件安全模块（HSM）或 密码密钥派生函数（KDF）。不接受使用任意人工设置的密码代替随机密钥。

在有计划的迁移 实施并验证之前，请保留现有安装中的现有密钥。删除 `vault.key` 或替换主密钥可能会导致 无法访问会话/签名密钥。请将加密备份与密钥分开存放，并 在隔离的环境中测试恢复功能。
