oclaw/docs/attachment-acl.md

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