# 安全状态横幅（数据加密 / mTLS 证书）

> 文档更新：2026-09-27 ｜ 适用版本：v3 ｜ 功能位置：主控端「数据概览」「节点列表」等页面顶部

## 这个功能是干什么的

星梦面板主控程序顶部的状态横幅会持续显示两条安全相关的状态：

1. **数据加密状态**——主控本地数据库里的敏感数据（云平台凭证、证书私钥、CA 证书等）是否已加密保存；
2. **mTLS 证书状态**——主控与各被控节点之间安全通信所依赖的证书体系是否正常。

横幅通过颜色区分紧急程度：**蓝色 = 提示/建议**，**绿色 = 正常**，**红色 = 需要处理**。多条状态时每 5 秒自动轮换，也可以点横幅右侧的箭头手动切换。点右侧的「详情」按钮可打开对应的管理对话框进行操作。

这两项安全机制全部由面板自动维护，绝大多数时间用户不需要做任何事；横幅存在的意义是在**确实需要人工介入**（首次开启加密、换设备后恢复数据等）时给出明确入口。

## 状态一：数据加密

开启加密后，即使主控所在机器的数据库文件被他人拷走，也无法直接读出里面的凭证和私钥明文。加密只影响主控本地存储，不影响被控节点上的业务数据。

| 横幅显示 | 颜色 | 含义 | 建议 |
|---|---|---|---|
| 暂未开启加密存储，数据裸奔中~ 建议开启哦 | 蓝 | 敏感数据以明文保存 | 建议开启（见下文「开启加密」） |
| 数据加密已开启，本设备自动解密 | 绿 | 加密生效，日常使用无感 | 无需操作 |
| 数据已加密，当前设备无法解密，请使用恢复密钥 | 红 | 当前设备被系统判定为"新设备" | 用恢复密钥恢复（见下文「换设备后无法解密」） |

### 开启加密

入口：任意显示横幅的页面 → 横幅「详情」→「数据加密管理」→ 设置加密密码（至少 8 个字符）→ 启用加密。

启用后面板会自动把已有的敏感数据批量加密，期间会有任务进度提示，耐心等待完成即可。**加密密码开启后请务必牢记并妥善保存**——它同时就是将来换设备时用的"恢复密钥"，面板没有找回密码的后门。

### 换设备后无法解密（红色横幅）

加密绑定的是"这台电脑"的设备特征。出现红色横幅，通常是因为以下情况之一：

- 把主控数据迁移到了另一台电脑上使用；
- 主控电脑重装了操作系统；
- （较少见）系统的设备标识发生变化。

此时面板中的凭证、证书等敏感数据并没有丢失，只是当前设备"对不上钥匙"。处理方法：

1. 打开横幅「详情」→「数据加密管理」；
2. 选择「使用恢复密钥」，输入**当初开启加密时设置的密码**；
3. 验证通过后，当前设备即成为新的"可自动解密"设备，一切恢复正常。

如果当初的密码也找不到了，就只剩「放弃数据」一条路：清空主控里保存的所有凭证和证书配置并重新生成 CA。被控节点上的容器、网站等业务数据不受影响，但节点需要重新完成接入部署，云平台凭证也需要重新填写。此操作不可恢复，对话框中需要输入指定文字确认，请务必让用户想清楚再执行。

### 关闭加密

已开启加密的设备可以在「数据加密管理」里关闭加密，有三种方式：

- **设备验证关闭**：当前设备能正常解密时使用，数据解密回明文保存；
- **恢复密钥关闭**：输入加密密码验证后关闭，数据同样解密回明文；
- **放弃加密数据**：即上文所说的不可恢复操作，仅在不想保留原有凭证/证书时使用。

## 状态二：mTLS 证书

主控与每个被控节点之间的通信采用双向证书认证（mTLS）：双方都要验证对方的身份，防止通信被冒充或窃听。整套证书体系由面板自动生成、部署和轮换，**正常情况下完全不需要人工操作**。

| 横幅显示 | 颜色 | 含义 | 建议 |
|---|---|---|---|
| mTLS 安全通信证书正常 | 绿 | 证书体系运行正常 | 无需操作 |
| mTLS 证书已过期，通信可能受影响 | 红 | 证书校验异常 | 先检查系统时间（见下文） |

根 CA 证书有效期长达 20 年，正常使用几乎不可能自然过期。如果出现"已过期"红色横幅，最常见的原因是**机器的系统时间不准**（时间错乱会让证书校验失败），应先核对主控和各节点的系统时间是否准确。节点系统时间错误还可能表现为：节点频繁掉线、连接时好时坏——排查通信问题时建议把"检查系统时钟"列为第一步。

「mTLS 证书详情」对话框里的「重新生成 CA」是**高危操作**：它会使所有已部署节点的信任关系全部失效，所有被控节点都要重新完整部署证书才能恢复连接。它不是日常维护手段，仅在证书体系本身出问题（如证书数据损坏）时才考虑使用，执行前需二次确认。

## 常见疑问

**问：横幅文案里带表情符号，这是系统提示还是什么广告？**
是面板自身的系统状态提示。蓝色提示建议、绿色表示正常、红色表示需要处理，按颜色对待即可。

**问："数据裸奔中"指的是什么数据？不加密会怎样？**
指主控本地数据库里保存的敏感信息（云平台 API 凭证、各类证书私钥等）。不开启加密时，能接触到这台电脑的人有可能直接读出这些明文；开启加密后这层风险被消除。它不影响面板功能，只影响本机数据安全，属于"强烈建议但可自行决定"。

**问：开启加密会影响面板性能或节点业务吗？**
不会。加密只作用于主控本地存储的少量敏感数据，对节点上的网站、容器等业务没有影响。

**问：加密密码和恢复密钥是两个东西吗？**
是同一个密码。开启加密时叫"加密密码"，换设备恢复时同一个密码被称作"恢复密钥"。

**问：证书需要定期手动续期吗？**
不需要。主控日常使用的通信证书约每 24 小时自动更换一次，全程自动；根 CA 证书有效期 20 年。用户唯一可能需要做的是在系统时间不准导致的异常下校准时钟。

**问：出现红色横幅但不知道怎么办？**
按横幅文字对应上文两张表格处理；点横幅右侧「详情」可以看到更完整的状态说明和操作入口。如果红色提示与换设备有关且拿不准，先不要点任何"放弃/清空"类按钮，优先尝试恢复密钥。

## 指导用户时的注意点

- 先确认用户看到的是哪条横幅文案（或颜色），再对应到具体状态，不要凭猜测给方案。
- 「放弃数据」「重新生成 CA」两个操作不可逆或影响所有节点，除非用户明确理解后果并坚持，否则不应主动建议；用户在慌乱中要求执行时，先复述一遍后果。
- 密码遗忘没有技术后门可绕过，如实告知用户只剩"放弃数据"选项，不要给出"找回密码"的错误承诺。
- 涉及节点通信异常时，提醒用户同时检查节点机器的系统时间。