# 安全说明

## 报告问题

**不要开公开 issue。** 请私下联系维护者（仓库主页的联系方式），说明影响范围与复现步骤。
我们会尽快确认并给出修复计划。

## 这个项目需要你知道的威胁模型

### 1. 管理后台 = 远程控制面

后台能改配置、编人格、重建会话、注入指令。它**默认只听 `127.0.0.1`**，请务必用
SSH 隧道访问：

```bash
ssh -L 8790:127.0.0.1:8790 <user>@<host>
```

口令只从环境变量读（`CHANNEL_QQ_ADMIN_PASSWORD_HASH`，scrypt 哈希优先）。不要把它
暴露到公网，也不要把口令写进配置文件或提交历史。

### 2. 群消息是**不可信输入**

群友可以往群里贴任意内容。所有来自 QQ 的文本都会包进
`<untrusted source="qq">` 信封交给模型；工具侧有注入特征扫描与信任分级：

- 高风险群管动作（踢人 / 全员禁言 / 设管理员）默认关闭，且只允许管理员发起的回合执行；
- 群聊准入（`planner`）在消息进 agent 之前就挡掉一部分；
- 工具档位按会话信任判定，非 QQ 会话不受影响。

**仍然不要**把带 root 权限的命令执行能力开放给任意群聊回合。

### 3. 协议端账号风险

NapCat 等协议端属于非官方实现，账号风控、掉线、要求重新验证都是常态。
**重启容器 / 重启 Docker / 换版本都会导致登录态失效，需要人工扫码。**
不要为了排障而反复重建容器。

### 4. 审批网关（已启用）

高危命令（重启服务、装包、发布、删文件、改系统配置）的放行依赖人工审批：
命令提交后绑定哈希，批准生成一次性令牌，执行前三样全核（请求号 / 过期 / 哈希）。
批准指令只认管理员私聊，且**不经模型**。

## 部署清单

- [ ] 后台只监听 `127.0.0.1`
- [ ] 口令用 scrypt 哈希，存环境变量，文件权限 600
- [ ] OneBot access token 随机生成，不写进仓库
- [ ] 工作区（`workspacePath`）与日志目录不与系统目录混用
- [ ] 备份任务启用（`deploy/workspace-backup.sh`）
- [ ] 发布走 `deploy/release.mjs`（验签 + 原子切换 + 一条命令回滚）