InfoGenie/infogenie-backend-go/后端文档.md

万象口袋 — Go 后端文档

技术栈：Go 1.25+ · Gin · GORM · MySQL ·（可选）Redis（go-redis v9）

模块路径：infogenie-backend（见 go.mod）

入口：cmd/server/main.go — 加载配置、连接 MySQL、cache.Init（若启用 Redis）、AutoMigrate、启动 HTTP 服务。

---

Docker 生产部署（预编译二进制）

1. 本机（Windows）：在 infogenie-backend-go 目录运行 build-linux-amd64.bat，生成 dist/server（Linux amd64）。
2. 构建镜像：docker compose up -d --build（默认使用 Dockerfile.prebuilt，不在服务器执行 go build）。
3. 若要在镜像内编译：docker compose -f docker-compose.yml -f docker-compose.sourcebuild.yml up -d --build（使用原 Dockerfile 多阶段构建）。
4. 端口：docker-compose.yml 映射 12364:5002；浏览器访问的 API 基址须与前端 VITE_API_URL 一致（HTTPS 反代或公网可达地址）。
5. .env.production：容器内 DB_HOST=127.0.0.1 指向容器自身，不能访问宿主机 MySQL。MySQL/Redis 在宿主机时见仓库内 .env.production.example 注释（如 172.17.0.1、host.docker.internal）。REDIS_ENABLED=true 时 Redis 必须可达，否则进程启动即失败。

---

运行与配置

• 环境由 **APP_ENV** 决定：development 或 production（见 config.Load()）。
• 若存在 **.env.development** / **.env.production**，会通过 godotenv 加载对应文件。
• **APP_PORT** 默认 5002（与前端 VITE_API_URL 开发默认一致）。
• 数据库、邮件、认证中心、INFOGENIE_SITE_ADMIN_TOKEN、可选 Redis 等从环境变量读取，详见 config/config.go。

Redis（可选）

变量	说明
REDIS_ENABLED	true / 1 / yes / on 时启用；未启用则不连 Redis，站点接口直连 MySQL
REDIS_ADDR	host:port；生产环境必填；开发未设时默认 10.1.1.100:6379
REDIS_PASSWORD	可选
REDIS_DB	逻辑库编号，默认 10（与 db0 等业务隔离）
REDIS_KEY_PREFIX	Key 前缀，默认 infogenie:go:v1:（可自动补 :）
REDIS_SITE_TTL	站点类 JSON 缓存 TTL（秒），默认 60

启用时启动阶段会 Ping；失败则进程退出。站点只读接口对 60s-disabled、60s-source、ai-model-disabled、feature-card-clicks 等做 cache-aside，管理端写入成功后删对应 Key（见 internal/cache/redis.go 与 internal/handler/siteconfig.go、feature_card_clicks.go）。

---

健康与诊断

GET /api/health（公开）

• **status**：running 或 degraded（MySQL 未连通 或 60s 上游探测失败时为 degraded；不因 Redis 失败而 degraded）。
• **mysql**：ok、status（connected / disconnected / not_initialized）。
• **sixty_api**：当前生效的上游 source_id、base_url、label，以及对 …/v2/ip 的探测结果（probe_url、http_status、latency_ms、error）。
• **redis**：未启用时 { "enabled": false }；启用时 { "enabled": true, "ok": bool, "error"?: string }。

GET /api/admin/site/diagnostics（需管理员）

请求头 **X-Site-Admin-Token** 须与 **INFOGENIE_SITE_ADMIN_TOKEN** 一致。

返回不含密码明文，仅连接与进程摘要，供运维/后台展示：

字段	内容
app	env、listen_addr（0.0.0.0:端口）、listen_port
mysql	host、port、database、user、password_configured
redis	enabled；若启用则含 addr、logical_db、key_prefix、site_cache_ttl_sec、password_configured
sixty_upstream	库内当前 60s 节点 source_id / base_url / label
auth_center	api_url
mail	SMTP host、port、username、password_configured

---

根路径：GET / — 返回服务说明与主要 endpoint 分组（version 当前为 3.3.0-go）。

---

数据库（GORM AutoMigrate）

启动时会迁移以下模型（见 internal/database/mysql.go）：

模型	用途
AIConfig	多厂商 AI Key / Base / 模型列表（如 deepseek、kimi）
Site60sDisabled	60s 功能在前端隐藏的 feature_id
SiteAIRuntime	DeepSeek 兼容网关（Base + Key + 默认模型），优先级高于部分 AIConfig
Site60sUpstream	60s 上游节点（单例 id=1）
SiteAIModelDisabled	AI 应用在前端隐藏的 app_id
SiteFeatureCardClick	四大板块功能卡片点击统计（section + item_id 联合主键）

---

路由概览（internal/router/router.go）

CORS

全局 middleware.CORS()，放行常用 Method/Header（含 Authorization、X-Site-Admin-Token）。

认证与用户

方法	路径	说明
GET	/api/auth/check	可选 JWT：校验登录态
GET	/api/user/profile	需 JWT：用户资料

实际登录、发 token 由 萌芽账户认证中心 完成；后端校验 JWT。

站点公开配置（无需登录）

方法	路径	说明
GET	/api/site/60s-disabled	被隐藏的 60s feature_id 列表
GET	/api/site/60s-source	60s 上游 source_id / base_url
GET	/api/site/ai-model-disabled	被隐藏的 AI 应用 id 列表
GET	/api/site/feature-card-clicks?section=	功能卡片点击次数（见下）
POST	/api/site/feature-card-clicks/increment	上报一次点击，返回最新 count

**section 合法值**：60sapi · smallgame · toolbox · aimodel

increment 请求体：{ "section": "...", "item_id": "..." }

站点管理（需 X-Site-Admin-Token，与环境变量 INFOGENIE_SITE_ADMIN_TOKEN 一致）

方法	路径	说明
PUT	/api/admin/site/60s-disabled	更新 60s 隐藏列表
PUT	/api/admin/site/60s-source	切换 60s 上游
PUT	/api/admin/site/ai-model-disabled	更新 AI 应用隐藏列表
GET/PUT	/api/admin/site/ai-runtime	读取/更新 DeepSeek 兼容运行时配置
GET	/api/admin/site/diagnostics	连接与进程配置快照（不含密钥明文）

AI 应用（/api/aimodelapp，默认 需 JWT）

方法	路径	说明
POST	/chat	非流式对话，JSON 返回全文
POST	/chat/stream	SSE 流式：透传上游 OpenAI 兼容流（text/event-stream）
POST	/name-analysis 等	各垂直能力（姓名、变量命名、写诗、翻译等）
GET	/models	模型列表

流式说明（internal/handler/aimodel.go + internal/service/ai.go）：

• 上游请求带 stream: true，成功后将上游 body 分块写入并 Flush 到客户端。
• 支持 deepseek（运行时或 AIConfig）与 kimi（AIConfig）。
• 与 /chat 共用同一套 bindAIModelChat 校验（消息条数、长度、模型白名单等）。

模型白名单：见 internal/handler/aimodel.go 中 allowedModels（如 deepseek-chat、deepseek-reasoner、部分 kimi 模型）。

---

核心源码目录

cmd/server/          # main
config/              # 配置加载（含 Redis）
internal/
  cache/             # Redis 可选封装（Get/Set JSON、Delete、Ping）
  database/          # MySQL 初始化、AutoMigrate
  handler/           # HTTP 处理器（auth、user、aimodel、siteconfig、ai_runtime、feature_card_clicks）
  middleware/        # CORS、JWT
  model/             # GORM 模型
  router/            # 路由注册（含 /api/health、diagnostics）
  service/           # AI 调用（含 OpenAI 兼容非流式与流式）
scripts/redis_keyspace/   # 可选：本地查看各逻辑库 keyspace（go run，需 REDIS_PASSWORD）

---

与其他工程的关系

• 前端 SPA 通过 VITE_API_URL 指向本服务（开发默认 http://127.0.0.1:5002）。
• **public/aimodelapp/*/shared/ai-chat.js** 优先调用 /api/aimodelapp/chat/stream，失败时回退 /chat。

更完整的前端集成说明见 **infogenie-frontend/前端文档.md**。