Files
knowledge-governance/docs/SOURCE_AUTH_CONFIGURATION.md
T
姚章浩 3825859da6
build / build (push) Successful in 2m20s
feat(settings): 打通 PP 认证配置并统一 DWS 来源授权
PP 增加受控凭据更新、真实登录与目录检查,待验证修改不会替换生效配置;扫描与取件共享生效修订。
钉钉来源向导、校验与登记共用 DWS 授权,支持中途恢复与换账号保护,取消旧扫码自动回落。
认证审计复用已有来源审计页,配置响应不回传密码;补齐运行镜像脚本与权限。

验证:make verify 退出 0;PP/DWS/httpapi 目标 race 回归通过;隔离 HTTP 服务验证 PP 协议及扫描/取件消费者。
尚未部署;真实 PP 凭据与目录可用性在测试站部署后验证。
2026-11-17 19:08:46 +08:00

5.3 KiB
Raw Blame History

数据源认证配置

管理员入口:系统设置 → 数据源配置。PP 连接位于钉钉账号卡旁;添加来源向导使用同一组账号与配置。

PP 连接

  • API 地址填写 HTTPS 根地址;后台沿用 /admin/login/token、/potal/file/back/page 接口路径。potal 是上游真实路径,不能改写。
  • 账号允许修改。密码只显示已配置/未配置;点击“更新密码”录入新值。省略或留空保留既有密码,不回显原值。
  • “测试连接”使用当前表单,真实登录并读取一条目录记录;合法空目录也可通过。它不保存配置、不登记来源、不启动扫描。
  • “保存并校验”在后端重新检查本次提交。通过后切换生效;明确的认证拒绝、权限拒绝、接口不兼容阻止生效。
  • 超时、限流或服务临时故障可保存为待验证修改;缺少凭据可保存未完成配置。两者都不会替换当前生效配置;需要再次保存并校验,通过后才切换。
  • 草稿测试结果与当前生效配置状态分开;每次修改字段会使原草稿测试结果作废。检查失败时保留上次观测及时间,不能把网络失败当成退出登录。
  • 后续目录扫描和远程取件读取同一生效配置;验证过的本地文件仍按既有内容校验逻辑复用。配置保存不恢复暂停的计划、不触发入库或发布。

PP 服务端接线

参数 默认与用途
PP_AUTH_STATE_FILE /data/source-auth/pp/settings.json;API 和 worker 必须读同一份原子配置文件
PP_AUTH_PYTHON /usr/bin/python3;API 连接检查使用的解释器
PP_AUTH_CHECK_SCRIPT /app/scripts/pp_client.py;与扫描、取件共享的只读协议实现
PP_LEGACY_CREDENTIALS_FILE 可选,只用于首次迁移;有效状态文件存在后不再回落旧文件

配置目录及状态文件分别使用 0700 和 0600。API/worker 使用相同 UID,将宿主凭据目录挂载为共享目录,不能绑定单个文件:单文件 bind mount 会在原子 rename 后继续指向旧 inode。迁移时从目标机既有凭据文件直接读取,禁止通过聊天、命令行参数或仓库传递密码。

状态文件持有生效配置、待验证修改、最近检查及认证审计,包含密码,因此必须按密钥文件保护,不能进普通配置备份、版本记录或日志。更新使用跨进程文件锁、临时文件、fsync 和原子 rename。配置修订采用乐观并发控制;旧请求不能覆盖新修订。worker 的迟到检查只能更新自身生效配置 ID 对应的观测。

PP 检查子进程只从 stdin 接收本次凭据,stdout 只返回白名单检查结论。GET 接口仅返回配置元数据和是否存在密码;密码输入字段只可写。

接口 用途
GET /api/v1/pp-connection 管理员读取安全元数据、待验证修改与检查状态
POST /api/v1/pp-connection/test 测试当前草稿,不激活
PUT /api/v1/pp-connection 校验并保存;携带当前 revision

使用已保存的待验证密码继续校验时携带 pending_id,避免空密码误用旧生效密码。修改请求验证管理员、同源操作意图和输入大小;响应禁止缓存。

钉钉添加向导

保留 类型 → 授权 → 范围 → 校验 → 保存 五步;授权步骤复用钉钉账号卡的官方 DWS 设备授权流程。

  • 可见范围、校验和登记都使用共享 DWS 身份;登记不再自动回落旧扫码侧车。DWS 无法定位的历史空间返回明确原因。
  • POST /api/v1/dingtalk-spaces/validate 真实读取并检查所选空间。失败、权限不足、部分范围不完整与合法空列表分别展示。
  • 已接入空间按稳定空间身份标记,历史连接也从其存储的空间标识识别,不靠名称去重。
  • 保存中授权失效:保留已成功项及待处理项,在向导内重新授权;同账号恢复后继续剩余项,复用操作标识,首次扫描按连接身份去重。
  • 取消或失败后保留选择并停止自动提交;再次恢复失败不循环弹授权。
  • 授权后换账号/组织:重新加载范围并清除旧选择,要求重新确认。客户端提交身份指纹,后端在列举前后确认身份,变化时拒绝登记。
  • 只有已点击保存的操作才会在重新授权后继续登记;账号登录、刷新和连接检查本身不创建来源或扫描任务。
  • 登记成功和首次扫描入队分别反馈,不能用登记成功冒充扫描已运行。

其他历史入口若仍调用旧扫码侧车,保留其原行为;本功能不删除整个侧车服务。

审计与验证

PP 配置/密码更新、连接检查及 DWS 授权结果,复用现有数据源操作审计页面。凭据事件与配置在同一文件内原子提交,并与数据库原有事件按时间合并分页;不把密码写入 SQL。DWS 终态审计按授权 ID 与状态去重,轮询不刷记录。

回归覆盖真实协议请求、空目录、认证拒绝、权限与限流、密码保留/替换、待验证密码重校验、并发修订冲突、响应脱敏、同源及角色限制、无意外任务、审计分页、DWS 部分成功恢复与换账号保护。协议与消费者测试使用隔离的本机 HTTP 服务;运行环境可用性需另行通过真实页面检查,不能用这些用例替代。