Agent Portal — 03-17~18 独立部署与认证统一

关键产品决策

• Dad 决策：拆分为独立 Agent
• 将原先一个代理管理多个项目的模式拆分，每个项目独立成 agent，隔离 workspace / context / cron
• 主 researcher 只保留统筹与研究职责

• 原因：单 agent 管多个项目导致上下文臃肿、任务边界不清、同步链路复杂

• Dad 决策：开发环境也必须登录

• 放弃"HTTP 开发环境跳过 LogtoProvider"方案，开发环境也必须登录，不能跳过认证

• 原因：需要保持完整认证链路的一致性

• Dad 决策：domain 命名调整

• 初始 portal 子域名被改为 agent-project.clawlines.net
• 原因：portal 这个名字不合适，需要更明确的项目关联性

技术问题与根因分析

容器化部署方案确定

• 技术方案：使用 Docker Compose 统一编排
• 目标服务器：claw-runtime（Korea Central，IP 20.214.152.42）
• 镜像从 ACR externalacr.azurecr.io 拉取
• 先启动 client-web 和 gateway，其他服务按 profile 控制
• 选型理由：比散装脚本部署更可维护，便于多站点/多服务统一管理

Logto SPA 认证接入

• 根因：HTTP 下 Logto 依赖 Crypto.subtle，浏览器强制要求 HTTPS
• 解决方案：
• 使用现有 Docker 内的 Caddy 统一做 HTTPS 反代
• 利用通配符 DNS *.dora.restry.cn
• Vite 增加 allowedHosts 以允许 dev 子域名访问
• 最终域名：portal.dev.dora.restry.cn

Caddy 配置热更新问题

• 现象：修改宿主机 Caddyfile 后容器内配置未更新，Caddy reload 显示 config is unchanged
• 根因：使用会替换 inode 的写法，Docker bind mount 绑定旧 inode
• 解决方案：改用 sed -i 原地修改，保持 inode 不变
• 经验：对 bind mount 配置文件做热更新时，避免"写新文件替换旧文件"的方式

Logto Management API 打通

• 根因：M2M 应用属于 admin tenant，却错误调用了 default tenant 的 OIDC endpoint
• 解决方案：改用 admin tenant 的 token endpoint（域名为 logto.admin.dr.restry.cn）

Bot 架构/实现决策

项目目录结构调整

• 决策：agent 本身就是 project，不再保留额外 project/ 目录层
• 实施：将项目产出物与标准文件合并到 agent 外层记忆结构
• 修复：更正 AGENTS.md 中仍引用旧 project/ 路径的问题

认证流程整合

• 技术架构：前端采用 Logto SPA 模式，与其他项目保持一致
• 配置管理：通过 Management API 自动创建应用，避免直接写数据库
• 安全策略：统一身份认证，所有 SPA 应用接入同一认证中心

里程碑

1. 独立 Agent 化完成：Portal 从 researcher 子项目拆分为独立 portalbot 维护
2. Logto 认证接入：完成 SPA 认证接入，commit 803c869，认证链路正常
3. 容器化部署就绪：纳入统一容器化部署与 ACR 镜像发布流程
4. 开发环境域名化：dev 环境从 http://dev.dora.restry.cn:18813 升级为 HTTPS 子域名方案
5. 跨 Agent 通信打通：解决 bot 间 DM 权限，sessions_spawn 和 Mattermost DM 通道修通

重要配置线索

• 域名：agent-project.clawlines.net（生产）、portal.dev.dora.restry.cn（开发）
• 服务器：claw-runtime (20.214.152.42)
• 镜像仓库：externalacr.azurecr.io
• 认证：Logto admin tenant endpoint
• 文档资产：docs/logto-spa-integration-guide.md

这一阶段奠定了 Agent Portal 的独立运行基础和统一认证体系，为后续功能扩展提供了稳定的部署和认证支撑。