mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-09 03:30:48 +08:00
oliver
31e3962c74
This persists referenced media safely, adds explicit attachment ACL/backfill flows, and fixes the Weixin sidecar so official login state can bridge reliably into oclaw without duplicate replays or dropped replies. Made-with: Cursor
72 lines
2.1 KiB
Markdown
72 lines
2.1 KiB
Markdown
# Attachment ACL（附件访问控制）
|
||
|
||
本文档说明 admin chat 附件下载鉴权的访问控制策略、回填流程与 strict 模式上线建议。
|
||
|
||
## 背景
|
||
|
||
系统把工具结果/上传文件等二进制内容落盘为 `attachment_id`（内容 hash），前端通过：
|
||
|
||
- `GET /admin/api/chat/attachments/{attachment_id}`
|
||
|
||
获取附件 bytes（下载/预览）。
|
||
|
||
为避免仅凭 `attachment_id` 造成越权读取，需要对下载接口做归属校验。
|
||
|
||
## 数据结构
|
||
|
||
- **`attachment_acl`**
|
||
- 用途：记录附件归属关系（哪个租户/用户/会话以何种来源产生/引用了该附件）
|
||
- 主键：`(attachment_id, tenant_id, user_id, session_id, source)`
|
||
|
||
## 鉴权策略
|
||
|
||
下载接口会校验：
|
||
|
||
- `attachment_id` 格式合法（64 位 hex）
|
||
- 当前登录用户是否被 ACL 授权访问该附件
|
||
- 头像附件通过 `avatar_attachment_id` 放行（不走 ACL）
|
||
|
||
## strict 模式
|
||
|
||
环境变量：
|
||
|
||
- `AIA_ATTACHMENT_ACL_STRICT=1`
|
||
|
||
行为：
|
||
|
||
- 下载鉴权只信 `attachment_acl`（以及头像 `avatar_attachment_id`）
|
||
- **不会**回退扫描历史 `chat_message.attachments`
|
||
|
||
适用场景：
|
||
|
||
- 生产环境附件访问收口
|
||
- 已完成历史数据 ACL 回填
|
||
|
||
## 回填流程（Admin）
|
||
|
||
为了让历史消息中的附件也能被 strict 模式识别，需要先回填 ACL。
|
||
|
||
入口（仅 `administrator` 可见/可调用）：
|
||
|
||
- 管理台 Chat 页面右上角菜单：**回填 ACL**
|
||
- 或接口：`POST /admin/api/chat/admin/attachments/acl/backfill?limit_messages=...`
|
||
|
||
建议流程：
|
||
|
||
1. 在低峰期执行回填（默认扫描最近 50k 条含 attachments 的消息）
|
||
2. 观察返回结果（扫描/插入计数）
|
||
3. 开启 `AIA_ATTACHMENT_ACL_STRICT=1`
|
||
|
||
## 相关配置放一起（ENV）
|
||
|
||
- `AIA_MAX_ATTACHMENT_BYTES`：控制工具结果 base64 落盘单附件大小上限
|
||
- `AIA_ATTACHMENT_ACL_STRICT`：下载鉴权严格只信 `attachment_acl`
|
||
|
||
## 回滚建议
|
||
|
||
如 strict 模式误伤历史附件下载（403）：
|
||
|
||
1. 临时关闭 strict：`AIA_ATTACHMENT_ACL_STRICT=0`
|
||
2. 再次执行回填（提高 `limit_messages`）
|
||
3. 重新开启 strict
|
||
|