|
|
@@ -0,0 +1,151 @@
|
|
|
+# 后端重构与环境隔离规划
|
|
|
+
|
|
|
+## 1. 技术锐评 (Technical Review)
|
|
|
+
|
|
|
+### 1.1 架构层面
|
|
|
+* **环境隔离缺失**：当前主要依赖在 `app.conf` 中手动注释/取消注释代码块来切换环境（如 MySQL 配置、认证地址）。这种方式极易出错，且难以在 CI/CD 流程中自动化。
|
|
|
+* **硬编码泛滥**：
|
|
|
+ * `utils/config.go` 中直接硬编码了生产环境 URL (`https://aqai.shudaodsj.com:22000`)。
|
|
|
+ * `controllers/` 下多个文件（`shudaooss.go`, `hazard.go`, `chroma.go` 等）硬编码了 IP 地址和端口（如 `172.16.17.52:8060`, `172.16.35.50:18080`）。
|
|
|
+ * 这导致代码与特定部署环境强耦合，本地开发和测试环境极易连接到错误的服务（如本地连上了生产库）。
|
|
|
+* **部署差异**：由于配置散落在代码中，部署到新环境（如测试环境）需要修改源码并重新编译，违反了 "Build Once, Run Anywhere" 原则。
|
|
|
+
|
|
|
+### 1.2 代码层面
|
|
|
+* **配置管理混乱**：没有统一的配置加载层。有的配置在 `app.conf`，有的在 `utils`，有的直接在 `controllers` 的常量或变量中。
|
|
|
+* **代码位置不当**：
|
|
|
+ * `views/` 目录下存在 `.vue` 文件 (`liushitest.vue`) 和测试 HTML 文件，这些是前端源码或临时测试文件，不应出现在 Go 后端项目的构建目录中。
|
|
|
+ * `chat.go` 被标记为已弃用但仍存在于项目中，造成维护困扰。
|
|
|
+* **可测试性差**：由于依赖硬编码的外部服务地址，单元测试难以在隔离环境下运行（必须有网络且对应 IP 可达）。
|
|
|
+
|
|
|
+### 1.3 重构难度评估
|
|
|
+* **成本**：**中等**。主要工作量在于全局搜索硬编码字符串并替换为配置读取逻辑。
|
|
|
+* **风险**：**低**。只要严格遵循"只读配置，不改逻辑"的原则，业务逻辑不会受影响。主要风险在于遗漏某些隐蔽的硬编码值。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 重构方案 (Refactoring Strategy)
|
|
|
+
|
|
|
+### 2.1 核心原则
|
|
|
+1. **单一数据源**：所有可变参数必须且只能在 `conf/app.conf` 中定义。代码中严禁出现 IP、端口、URL、密钥等字面量。
|
|
|
+2. **环境无侵入**：代码不感知当前是 "dev" 还是 "prod"，它只管读取配置。环境差异由 `app.conf` 的内容决定。
|
|
|
+3. **本地热重载**：利用 Beego 框架自带的 `bee run` 命令实现本地开发热重载。
|
|
|
+
|
|
|
+### 2.2 配置文件管理策略
|
|
|
+根据您的要求，采用 **"单文件 + 模板"** 策略：
|
|
|
+
|
|
|
+1. **`conf/app.conf`**：
|
|
|
+ * **加入 `.gitignore`**。
|
|
|
+ * 这是实际生效的配置文件，由开发者/运维在部署时手动创建和维护。
|
|
|
+2. **`conf/app.conf.example`** (新增)：
|
|
|
+ * **加入版本控制 (Git)**。
|
|
|
+ * 包含所有必要的配置项 Key，Value 留空或设为默认占位符。
|
|
|
+ * 包含详细的注释，说明每个配置项在不同环境（本地、测试、生产）应填写的典型值。
|
|
|
+
|
|
|
+### 2.3 目录结构调整建议
|
|
|
+```text
|
|
|
+shudao-go-backend/
|
|
|
+├── conf/
|
|
|
+│ ├── app.conf (被 git 忽略，实际配置)
|
|
|
+│ └── app.conf.example (新增，配置模板，含所有环境说明)
|
|
|
+├── utils/
|
|
|
+│ └── config.go (增强，提供类型安全的配置读取方法)
|
|
|
+├── controllers/ (移除硬编码，改为调用 utils.GetConfig)
|
|
|
+├── views/ (清理 .vue 和测试 html)
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 执行批次 (Execution Batches)
|
|
|
+
|
|
|
+### 第一批次：配置收拢与标准化 (Configuration Centralization)
|
|
|
+**目标**：消除代码中的硬编码，建立统一配置读取机制。
|
|
|
+
|
|
|
+1. **创建配置模板 `conf/app.conf.example`**：
|
|
|
+ * 整理所有散落在 `app.conf` 和代码中的配置项。
|
|
|
+ * 为 MySQL, Redis, OSS, YOLO, Chroma, DeepSeek, Qwen 等所有外部服务定义标准的 Key 命名（如 `oss_endpoint`, `yolo_base_url`）。
|
|
|
+ * 添加注释说明本地、测试、生产环境的推荐值。
|
|
|
+2. **增强 `utils/config.go`**：
|
|
|
+ * 封装 Beego 的 `AppConfig`，提供如 `GetString(key)`, `MustGetString(key)` 等方法，确保配置缺失时能快速报错（Fail Fast）。
|
|
|
+ * **修正**：修改 `GetProxyURL` 方法，不再硬编码域名，而是从配置读取 `base_url`。
|
|
|
+3. **替换 Controller 硬编码**：
|
|
|
+ * `controllers/shudaooss.go`: 替换 `ossEndpoint` 为配置读取。
|
|
|
+ * `controllers/hazard.go`: 替换 `yoloBaseURL` 为配置读取。
|
|
|
+ * `controllers/chroma.go`: 替换 `apiURL` 为配置读取。
|
|
|
+ * `controllers/chat.go`: 替换 `http://172.16.35.50:8000` 等硬编码地址。
|
|
|
+
|
|
|
+### 第二批次：代码清理与环境准备 (Cleanup & Environment Setup)
|
|
|
+**目标**：清理废弃代码和无关文件，确保项目纯净。
|
|
|
+
|
|
|
+1. **清理前端残留**：
|
|
|
+ * 删除 `views/liushitest.vue`。
|
|
|
+ * 移动或删除 `views/*.html` 测试文件（如果必须保留，移至 `tests/test_data/` 或类似目录，不要混在视图层）。
|
|
|
+2. **处理弃用代码**：
|
|
|
+ * 将 `controllers/chat.go` 和 `models/chat.go` 移动到 `_deprecated/` 目录（或直接删除，如果确认无用），并在文件名加 `_deprecated` 后缀，防止误引用。
|
|
|
+ * *注意：如果前端仍依赖某些接口路径，需确认微服务网关是否已接管这些路径。如果后端仍需保留接口定义但转发流量，需重写为代理模式（Proxy）。鉴于您提到"前端有用"，建议先保留文件但清理内部逻辑，或确认前端调用地址已变更。*
|
|
|
+3. **本地热重载验证**：
|
|
|
+ * 确认开发环境安装了 `bee` 工具。
|
|
|
+ * 使用 `bee run` 启动项目，验证修改文件后是否自动重新编译。
|
|
|
+
|
|
|
+### 第三批次：验证与文档 (Verification)
|
|
|
+**目标**：确保重构后各环境功能正常。
|
|
|
+
|
|
|
+1. **本地环境验证**：
|
|
|
+ * 复制 `app.conf.example` 为 `app.conf`。
|
|
|
+ * 配置为本地参数（连接本地/开发库）。
|
|
|
+ * 启动服务，验证基础接口。
|
|
|
+2. **测试/生产环境验证指南**：
|
|
|
+ * 编写 `DEPLOY.md`，说明在新环境部署时如何准备 `app.conf`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 风险点与检查清单 (Risks & Checklist)
|
|
|
+
|
|
|
+* [ ] **风险**：`app.conf` 中的 Key 命名变更导致旧代码读取失败。
|
|
|
+ * **对策**：在 `utils/config.go` 中使用 `MustGet` 类方法，如果配置缺失直接 Panic，避免静默失败。
|
|
|
+* [ ] **风险**：OSS 或第三方服务的 URL 拼接逻辑错误（如多加了 `/`）。
|
|
|
+ * **对策**：统一使用 `strings.TrimRight(url, "/")` 处理配置项。
|
|
|
+* [ ] **风险**：`chat.go` 删除导致前端旧版本报错。
|
|
|
+ * **对策**：暂时保留 `chat.go` 文件，但将其内部逻辑标记为 `Deprecated`，并确认前端请求是否已路由到微服务。
|
|
|
+
|
|
|
+## 5. 附录：app.conf.example 预览
|
|
|
+
|
|
|
+```ini
|
|
|
+appname = shudao-chat-go
|
|
|
+httpport = 22001
|
|
|
+runmode = dev
|
|
|
+
|
|
|
+# ==========================================
|
|
|
+# 基础配置 (Base Config)
|
|
|
+# ==========================================
|
|
|
+# 本地: https://127.0.0.1:22000
|
|
|
+# 生产: https://aqai.shudaodsj.com:22000
|
|
|
+base_url = "https://aqai.shudaodsj.com:22000"
|
|
|
+
|
|
|
+# ==========================================
|
|
|
+# 数据库配置 (Database)
|
|
|
+# ==========================================
|
|
|
+mysql_user = "root"
|
|
|
+mysql_pass = "password"
|
|
|
+mysql_urls = "127.0.0.1"
|
|
|
+mysql_port = "3306"
|
|
|
+mysql_db = "shudao"
|
|
|
+
|
|
|
+# ==========================================
|
|
|
+# 外部服务 (External Services)
|
|
|
+# ==========================================
|
|
|
+# 认证服务
|
|
|
+auth_api_url = "http://127.0.0.1:28004/api/auth/verify"
|
|
|
+
|
|
|
+# OSS 配置
|
|
|
+oss_endpoint = "http://172.16.17.52:8060"
|
|
|
+oss_access_key = "..."
|
|
|
+oss_secret_key = "..."
|
|
|
+oss_bucket = "gdsc-ai-aqzs"
|
|
|
+
|
|
|
+# 模型服务
|
|
|
+deepseek_api_url = "https://api.deepseek.com"
|
|
|
+deepseek_api_key = "..."
|
|
|
+
|
|
|
+yolo_base_url = "http://172.16.35.50:18080"
|
|
|
+```
|
XieXing