feat: admin端UI

deploy-6.27.md

@@ -0,0 +1,92 @@
+# sundynix-agentix 服务部署与基建解耦方案分析（2026-06-27）
+
+> **分析背景**：在当前版本的部署架构中，网关、调度中心、Go/Python MCP 服务连接底层基建（NATS/PostgreSQL/Redis/Milvus/Neo4j）的配置依赖于系统环境变量（`os.Getenv`）。在本地开发时回退至硬编码的 `localhost` 默认值，在生产环境则需通过 `.env` 和 `docker-compose.prod.yml` 强绑定注入。
+>
+> **核心痛点**：缺乏应用启动时的动态引导机制，服务包与特定环境配置紧密耦合，无法在应用首次运行（如 Admin 控制台启动时）动态引导用户完成数据库和消息总线的连接配置并持久化，限制了软件的“开箱即用”体验。
+
+---
+
+## 一、 “鸡生蛋” 引导瓶颈分析
+
+在微服务体系下，通过 Web UI 配置底层连接会遇到经典的**自引导（Bootstrapping）矛盾**：
+
+```
+┌────────────────────────────────────────────────────────┐
+│                      自引导矛盾                        │
+├────────────────────────────────────────────────────────┤
+│ 1. Gateway 必须连接 Postgres 才能存储配置               │
+│ 2. Gateway 必须连接 NATS 才能与其它服务通信            │
+│ 3. 用户必须通过 Gateway API 才能访问 Admin 控制台       │
+│                                                        │
+│ 结论：Gateway 连接“打通前”，无法使用基于系统的配置中心。 │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、 三种解耦设计方案对比
+
+为了打破上述瓶颈，实现基建安装部署与服务的平滑解耦，有以下三种方案可供选择：
+
+### 方案 A：云原生标准模式（配置文件挂载）
+- **设计原理**：服务在启动时，不直接读取环境变量，而是读取映射挂载到容器内的特定配置文件（如 `/etc/sundynix/config.yaml` 或 `.env`）。如果文件不存在，服务在控制台报错并退出。
+- **配置流转**：
+  ```
+  [外部挂载卷/本地文件] ──> [服务加载] ──> [建立连接池]
+  ```
+- **适用场景**：面向 DevOps 工程师、IT 运维人员的私有化部署。
+- **优缺点**：
+  - *优点*：符合云原生 **12-Factor App** 规范，便于集成 K8s ConfigMap，逻辑简单、系统无额外状态。
+  - *缺点*：需要操作服务器文件（通过命令行编辑），非技术人员上手门槛高。
+
+### 方案 B：开箱即用引导模式（内存自备/SQLite 引导 + 重写配置文件）
+- **设计原理**：网关在检测不到基建配置时，自动进入 **安装模式（Setup Mode）**。此时网关不需要外部 PG 或 NATS，只在内存中运行轻量 HTTP 服务，或用单文件本地数据库（SQLite）临时保存连接状态，并渲染出“安装向导”网页。
+- **配置流转**：
+  ```
+  [无配置启动] ──> [启动本地 SQLite] ──> [Web 安装向导引导用户输入]
+  └─> [测试外部基建连接] ──> [成功] ──> [重写本地 env/config] ──> [自动重启服务]
+  ```
+- **适用场景**：面向企业普通 IT 管理员的商业化/独立包部署（类似于 WordPress、Jira、GitLab 的首次安装向导）。
+- **优缺点**：
+  - *优点*：用户体验极佳，不需要接触命令行，完全通过 Web 页面拖拽配置即可完成“一把拉起”。
+  - *缺点*：服务内部逻辑变得复杂，代码需支持“Setup 状态”与“Running 状态”的切换；涉及重写宿主机配置并自动重启进程的权限问题。
+
+### 方案 C：企业级微服务模式（外部配置中心）
+- **设计原理**：应用包内只配置一个非常轻量的配置中心连接信息（如 Nacos, Consul, Apollo 地址），服务启动后从配置中心拉取 NATS、DB 的连接串，并监听连接变更。
+- **配置流转**：
+  ```
+  [拉取配置中心连接] ──> [从 Consul/Nacos 获取 DB/NATS 凭据] ──> [热重载连接池]
+  ```
+- **适用场景**：大型企业分布式集群部署、SaaS 平台。
+- **优缺点**：
+  - *优点*：企业内网运维极其标准化，连接凭据集中管理，支持动态热变更。
+  - *缺点*：引入了新的基建组件依赖（如必须先部署 Nacos），增加了中小微企业私有化部署的成本。
+
+---
+
+## 三、 对比矩阵与架构建议
+
+| 维度 | 方案 A（配置文件挂载） | 方案 B（Web 安装向导） | 方案 C（外部配置中心） |
+| :--- | :---: | :---: | :---: |
+| **上手门槛** | 中等（需编辑文件） | **极低（Web 界面）** | 高（需运维配置中心） |
+| **开发复杂度** | **极低** | 高（需状态机与重启机制） | 中等（需集成配置 SDK） |
+| **部署维护性** | **优秀（云原生标准）** | 中等（文件读写权限限制） | 优秀（集中管理） |
+| **额外基建依赖** | 无 | 无 | **有（Nacos/Consul）** |
+| **企业接受度** | 80% | 95% | 60% |
+
+### 🛠️ 改造路线建议
+
+为了兼顾开发效率与用户体验，建议采用**渐进式重构路线**：
+
+1. **短期优化（方案 A 的增强版）**：
+   规范化 `sundynix-gateway/config/config.yaml` 的加载逻辑。网关启动时，依次尝试读取以下来源的配置：
+   1. 系统环境变量（最高优先级，便于 Compose 和 K8s 部署）
+   2. 挂载在外部的 `config.yaml`（宿主机持久化）
+   3. 代码内硬编码的本地开发兜底值
+
+2. **中期重构（方案 B，引入轻量引导）**：
+   在网关增加 `Setup` 路由及状态机：
+   - 检查外部存储配置文件是否存在。若无，将网关状态置为 `StateSetup`。
+   - 在 `StateSetup` 下，API 仅暴露 `/api/v1/setup` 供 Admin 端提交 Postgres DSN、Redis 地址和 NATS 凭据。
+   - 提交后，网关在后台利用 Go 的底层 `driver` 测试连接有效性。
+   - 通过测试后，使用 `os.WriteFile` 重写 `.env` 文件，并调用系统信号（或使用 Supervisor/Docker 重启机制）实现进程重启，从而无缝滑入正常运行状态。