Agentic BI — 03-18 部署与环境¶

Logto 认证集成完成¶

里程碑达成¶

2026-03-18 07:40: Agentic BI × Logto 认证接入完成 - 提交: commit a85d104 推送到 main - 背景: 此前代码已完成但忘记推送，此次为补推操作

认证策略意义¶

Logto 集成使 Agentic BI 具备了： - 用户身份管理能力 - 企业级安全基础 - 多用户数据隔离可能性

Docker 容器修复¶

问题现象与定位¶

2026-03-18 08:30: 容器崩溃，报错信息：

ImportError: attempted relative import with no known parent package

根因分析¶

技术问题: - Dockerfile 中 uvicorn 启动入口错误：uvicorn main:app - COPY v1-simple/backend/ . 将 backend 平铺到 /app/ - 破坏了相对导入的包结构语义

正确方案: - 保留 backend 作为 package 目录 - 修正启动入口为 uvicorn backend.main:app

修复执行¶

解决流程: 1. 08:30: 问题定位与分析 2. 修复方案: 调整 Dockerfile 构建逻辑 3. 提交: commit db5a9d3 4. 自动构建: GitHub Actions 构建新镜像

二次修复¶

2026-03-18 08:47 ~ 09:01: 发现容器仍处于 crash loop - 问题: 返回 502 错误 - 解决: 进一步修复 Docker 配置 - 提交: commit 14c7a5a - 结果: 容器重建后恢复正常

HTTPS 开发环境配置¶

浏览器安全策略挑战¶

问题背景: Logto 登录在 HTTP 环境下受限 - Crypto.subtle API 仅在 HTTPS 下可用 - 开发环境登录链路不通

Dad 的关键决策¶

"开发环境也必须登录，不能跳过 LogtoProvider，HTTP fallback 方案不可接受"

这一决策明确了技术方向： - 拒绝 HTTP 降级方案 - 要求开发环境也采用 HTTPS - 确保生产与开发环境一致性

技术解决方案¶

Caddy + 通配符 DNS + HTTPS 子域名: - 利用现有 Docker Caddy 容器 - 通过 *.dora.restry.cn 通配符 DNS 自动签发 HTTPS - 为各项目配置 allowedHosts

域名策略演进¶

初始方案: *-dev.dora.restry.cn
最终方案: *.dev.dora.restry.cn
- 更简洁的命名规则 - 符合开发环境约定

错误代码清理¶

2026-03-18 10:57: - 4 个"跳过 Logto"相关 commit 全部 revert - 移除 HTTP fallback 代码 - 确保代码库只保留正确方案

端口策略优化¶

初始端口分配¶

Agentic BI dev 环境: - 前端: 18816 - 后端: 18817

端口策略调整背景¶

Dad 明确要求： - 不再使用 18800-18900 对外开放端口段 - 统一改为本地 loopback + Caddy 反代 - 使用 3000 系列端口

Caddy 配置问题修复¶

2026-03-18 15:09: Caddy reload 后仍连接旧端口 - 根因: bind mount inode 变化，容器内 Caddyfile 未更新 - 解决: 避免 open(path, 'w') 造成 inode 变化 - 方案: 改用 sed in-place 保持 inode 不变 - 结果: 配置生效，全部服务返回 200

最终端口策略¶

2026-03-20 10:14: 开发流程最终确认 - 原则: 只使用本地 3000 系列端口 - 访问: 通过 Caddy 反代到 SSL 开发域名 - 示例: web.dev.dora.restry.cn -> 3026

Portal 集成问题¶

Bot 健康检查问题¶

2026-03-18 15:38: @bibot 健康检查超时 - 现象: 没有执行真正检查，只是读取 CONTEXT.md - 结论: 需要更明确的健康检查与运行验证逻辑

Slug 识别错误¶

2026-03-18 23:20: 项目同步中 slug 提取错误 - 问题: 从标题 "Agentic BI Assistant" 错误提取为 agentic - 原因: 正则表达式 /^#\s+(\S+)/m 只取第一个单词 - 解决: - 优先使用目录名 fallback - 统一 detectSlug 逻辑 - 结果: Agentic BI slug 修正为 agentic-bi

技术经验总结¶

Docker 最佳实践¶

包结构保持: 避免 COPY 操作破坏 Python 包导入语义
启动入口规范: 使用完整的包路径作为 uvicorn 入口
构建验证: 本地验证 Docker 构建产物，避免线上失败

开发环境安全¶

一致性原则: 开发与生产环境保持相同安全级别
HTTPS 必备: 现代 Web API 依赖 HTTPS，不应降级
证书自动化: 利用通配符 DNS + Caddy 简化证书管理

端口管理策略¶

端口段规划: 明确不同用途的端口范围
本地开发: 优先使用 loopback + 反代，而非直接暴露
配置热重载: 注意 bind mount 的 inode 稳定性

项目集成规范¶

命名一致性: 确保项目 ID/slug 在各系统中保持一致
健康检查: 实现真正的功能性检查，而非文档读取
自动同步: 减少手动维护，提高数据一致性

里程碑时间线¶

时间	事件	状态
07:40	Logto 认证接入完成	✅
08:30	Docker ImportError 定位	🔧
08:49	Docker 修复提交	✅
09:01	容器恢复正常	✅
10:53	HTTPS 开发环境打通	✅
15:09	Caddy 配置修复	✅
23:20	Portal 同步修复	✅

这一天的工作集中解决了部署环境的各种技术问题，为 Agentic BI 的稳定运行和后续维护奠定了坚实基础。从容器化到 HTTPS 配置，从端口策略到系统集成，形成了完整的部署最佳实践。