From b57b13222615c442e26d5732de232ba9c71cc0be Mon Sep 17 00:00:00 2001
From: Alex-larget <33240357+Alex-larget@users.noreply.github.com>
Date: Tue, 17 Mar 2026 14:17:20 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E3=80=81=E5=AE=9A=E7=89=88?=
 =?UTF-8?q?=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../agent/后端工程师/evolution/2026-03-17.md  |  24 +++++
 .cursor/agent/团队/evolution/2026-03-17.md    |  16 +++
 .cursor/agent/开发助理/经验清单.md            |   1 +
 .cursor/agent/开发助理/项目索引/后端.md       |   1 +
 .cursor/agent/开发助理/项目索引/团队.md       |   1 +
 .cursor/agent/开发助理/项目索引/测试.md       |   1 +
 .cursor/agent/开发助理/项目索引/管理端.md     |   1 +
 .../管理端开发工程师/evolution/2026-03-17.md  |   7 ++
 .../agent/软件测试/evolution/2026-03-17.md    |   8 ++
 .../2026-03-17_性能优化与Redis缓存方案落地.md | 101 ++++++++++++++++++
 .cursor/meeting/README.md                     |   1 +
 miniprogram/app.js                            |   4 +-
 soul-api/.env.development                     |   5 +-
 soul-api/.env.production                      |   4 +
 soul-api/internal/router/router.go            |  24 ++++-
 开发文档/10、项目管理/运营与变更.md           |  25 +++++
 16 files changed, 220 insertions(+), 4 deletions(-)
 create mode 100644 .cursor/meeting/2026-03-17_性能优化与Redis缓存方案落地.md

diff --git a/.cursor/agent/后端工程师/evolution/2026-03-17.md b/.cursor/agent/后端工程师/evolution/2026-03-17.md
index 28ff0075..c82615fe 100644
--- a/.cursor/agent/后端工程师/evolution/2026-03-17.md
+++ b/.cursor/agent/后端工程师/evolution/2026-03-17.md
@@ -47,3 +47,27 @@
 ## 会议收尾（2026-03-17）
 
 - 源码优化 10 项全部完成；开发环境测试 10 通过 2 跳过
+
+---
+
+## 性能优化与 Redis 缓存方案落地（2026-03-17）
+
+### Redis 缓存
+
+- **internal/cache**：Get/Set/Del、GetString/SetString；Redis 不可用时回退 DB
+- **已缓存**：book/parts、hot、recommended、stats、config、章节 content
+- **失效**：InvalidateBookParts、InvalidateBookCache、InvalidateConfig、InvalidateChapterContent
+
+### OSS 上传
+
+- **internal/oss**：LoadConfig、Upload、Delete；失败回退本地
+- 配置从 system_config.oss_config 读取
+
+### /health
+
+- 返回 database、redis 连接状态（ok/disconnected/disabled）
+
+### 经验
+
+- Redis 容灾：未配置或失败时回退 DB，不阻塞业务
+- 缓存 key：soul:{业务}:{标识}
diff --git a/.cursor/agent/团队/evolution/2026-03-17.md b/.cursor/agent/团队/evolution/2026-03-17.md
index 54eba977..6c54aae8 100644
--- a/.cursor/agent/团队/evolution/2026-03-17.md
+++ b/.cursor/agent/团队/evolution/2026-03-17.md
@@ -48,3 +48,19 @@
 ## 会议收尾（2026-03-17）
 
 - 源码优化 10 项全部完成；功能测试流程定稿；开发环境测试 10 通过 2 跳过
+
+---
+
+## 性能优化与 Redis 缓存方案落地（2026-03-17）
+
+### 架构约定
+
+- **Redis 容灾**：不可用时回退 DB，不阻塞业务
+- **缓存 key**：soul:{业务}:{标识}
+- **OSS 上传**：优先 OSS，失败回退本地
+
+### 影响角色
+
+- 后端开发：cache、oss 包；/health 增强
+- 管理端开发工程师：OSS 配置后上传自动优先 OSS
+- 测试人员：test_upload.py、/health 验证、部署后回归缓存接口
diff --git a/.cursor/agent/开发助理/经验清单.md b/.cursor/agent/开发助理/经验清单.md
index 673ca7e6..e550249c 100644
--- a/.cursor/agent/开发助理/经验清单.md
+++ b/.cursor/agent/开发助理/经验清单.md
@@ -51,6 +51,7 @@
 | 2026-03-17 | 小程序、后端、团队 | 业务规则/bug 修复 | - | 代付美团式：读页→代付页→分享；PayNotify beneficiaryUserID 权益归发起人；detail 返回 initiatorUserId；目录 loading、最新新增 5 条折叠 |
 | 2026-03-17 | 小程序 | 业务规则 | - | 代付统一到代付页：gift=1&ref 打开 read 时 redirectTo 代付页，禁止在阅读页代付 |
 | 2026-03-17 | 软件测试 | 流程定稿 | testing SKILL | 功能测试流程：成功 ☑️、失败列问题、最终报告；scripts/test/功能测试流程.md、测试报告-环境与用例清单.md |
+| 2026-03-17 | 后端、团队 | 架构/最佳实践 | api-dev SKILL | Redis 缓存：parts/hot/recommended/stats/config/章节 content；容灾回退 DB；OSS 上传；/health 返回 database/redis 状态 |
 
 ---
 
diff --git a/.cursor/agent/开发助理/项目索引/后端.md b/.cursor/agent/开发助理/项目索引/后端.md
index 87375aed..354b2d4c 100644
--- a/.cursor/agent/开发助理/项目索引/后端.md
+++ b/.cursor/agent/开发助理/项目索引/后端.md
@@ -35,6 +35,7 @@ soul-api（Go + Gin + GORM + MySQL）提供三组路由：`/api/miniprogram/*`
 | 2026-03-17 | 会议：新版管理端迁移；router 补齐 users/rfm、journey-stats、shensheshou 共 5 个；确认 ossConfig | 进行中 |
 | 2026-03-17 | 会议：稳定版源码质量优化；敏感配置生产强制校验、新增 /api/admin/user/track、AdminWithdrawTest 环境限制 | 已完成 |
 | 2026-03-17 | 会议收尾：源码优化 10 项全部完成；开发环境测试 10 通过 2 跳过 | 已完成 |
+| 2026-03-17 | 性能优化会议：Redis 缓存接入（parts/hot/recommended/stats/config/章节 content）、容灾回退 DB；OSS 上传接入；/health 返回 database/redis 状态 | 已完成 |
 
 > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
 
diff --git a/.cursor/agent/开发助理/项目索引/团队.md b/.cursor/agent/开发助理/项目索引/团队.md
index 068c8974..0afdc8f5 100644
--- a/.cursor/agent/开发助理/项目索引/团队.md
+++ b/.cursor/agent/开发助理/项目索引/团队.md
@@ -28,6 +28,7 @@ Soul 创业派对全项目架构与约定：路由隔离（miniprogram/admin/db
 | 2026-03-16 | 乘风发起例行开发进度同步 | 已完成 |
 | 2026-03-16 | TipTap Mention 需 data-label 规则；链接人与事与存客宝对接优化会议收尾 | 已完成 |
 | 2026-03-17 | 代付美团式流程与权益归属约定：读页→代付页→分享；权益/分佣归发起人；PayNotify beneficiaryUserID | 已完成 |
+| 2026-03-17 | 性能优化与 Redis 缓存方案落地：Redis 容灾回退 DB、OSS 上传容灾；/health 返回 database/redis 状态 | 已完成 |
 
 > **格式说明**：每次架构级讨论后在此追加一行，日期格式 YYYY-MM-DD
 
diff --git a/.cursor/agent/开发助理/项目索引/测试.md b/.cursor/agent/开发助理/项目索引/测试.md
index de3591f3..8ac67a6f 100644
--- a/.cursor/agent/开发助理/项目索引/测试.md
+++ b/.cursor/agent/开发助理/项目索引/测试.md
@@ -29,6 +29,7 @@
 | 2026-03-16 | 会议：new-soul 新需求与当前项目差异分析；引入派对AI 时回归文章上传/飞书推送/小程序展示 | 已完成 |
 | 2026-03-17 | 会议：稳定版源码质量优化；每项小回归、全部完成后完整三端联调 | 待续 |
 | 2026-03-17 | 会议收尾：功能测试流程定稿、测试报告模板、开发环境 10 通过 2 跳过 | 已完成 |
+| 2026-03-17 | 性能优化会议：test_upload.py 6 用例；/health 可验证 database/redis；部署后回归缓存接口 | 已完成 |
 
 ---
 
diff --git a/.cursor/agent/开发助理/项目索引/管理端.md b/.cursor/agent/开发助理/项目索引/管理端.md
index 2d089e22..68f6d635 100644
--- a/.cursor/agent/开发助理/项目索引/管理端.md
+++ b/.cursor/agent/开发助理/项目索引/管理端.md
@@ -40,6 +40,7 @@
 | 2026-03-17 | 修复 DistributionPage Order.description；用户余额人工调整（后端 adjust API + 用户详情入口）；代付列表页（后端 gift-pay-requests + 推广中心 Tab） | 已完成 |
 | 2026-03-17 | 会议：稳定版源码质量优化；UserDetailModal 改 /api/admin/user/track、RichEditor HTML 转义 | 已完成 |
 | 2026-03-17 | 会议收尾：源码优化已落地；开发环境测试通过 | 已完成 |
+| 2026-03-17 | 性能优化会议：OSS 配置后上传自动优先 OSS，失败回退本地；无需前端改动 | 已完成 |
 
 > **格式说明**：每次开发后在此追加一行，日期格式 YYYY-MM-DD，状态用：已完成 / 进行中 / 待续 / 搁置
 
diff --git a/.cursor/agent/管理端开发工程师/evolution/2026-03-17.md b/.cursor/agent/管理端开发工程师/evolution/2026-03-17.md
index 3951ba39..e34314e8 100644
--- a/.cursor/agent/管理端开发工程师/evolution/2026-03-17.md
+++ b/.cursor/agent/管理端开发工程师/evolution/2026-03-17.md
@@ -10,3 +10,10 @@
 ## 会议收尾（2026-03-17）
 
 - 源码优化已落地；开发环境测试通过
+
+---
+
+## 性能优化会议（2026-03-17）
+
+- **OSS 上传**：系统设置保存 OSS 配置后，上传接口自动优先 OSS；失败回退本地
+- 无需前端改动，后端 upload handler 已支持
diff --git a/.cursor/agent/软件测试/evolution/2026-03-17.md b/.cursor/agent/软件测试/evolution/2026-03-17.md
index 9deb7e59..5a030887 100644
--- a/.cursor/agent/软件测试/evolution/2026-03-17.md
+++ b/.cursor/agent/软件测试/evolution/2026-03-17.md
@@ -21,3 +21,11 @@
 - **功能测试流程定稿**：`scripts/test/功能测试流程.md` — 成功 ☑️、失败列问题、最终报告
 - **测试报告模板**：`scripts/test/测试报告-环境与用例清单.md` — 环境、用例、结果记录
 - **开发环境测试**：10 通过、2 跳过、0 失败
+
+---
+
+## 性能优化会议（2026-03-17）
+
+- **test_upload.py**：6 个用例（上传成功、鉴权、校验、删除）
+- **/health**：可验证 database、redis 连接状态
+- **部署后回归**：parts、hot、config、章节阅读等缓存接口
diff --git a/.cursor/meeting/2026-03-17_性能优化与Redis缓存方案落地.md b/.cursor/meeting/2026-03-17_性能优化与Redis缓存方案落地.md
new file mode 100644
index 00000000..6217d7d4
--- /dev/null
+++ b/.cursor/meeting/2026-03-17_性能优化与Redis缓存方案落地.md
@@ -0,0 +1,101 @@
+# 会议纪要 - 2026-03-17 | 性能优化与 Redis 缓存方案落地
+
+> 本文件由**助理橙子**在会议结束后自动生成。
+
+---
+
+## 基本信息
+
+- **时间**：2026-03-17
+- **议题**：三端性能优化、Redis 缓存接入、OSS 上传、健康检查增强
+- **参与角色**：后端开发、管理端开发工程师、小程序开发工程师、测试人员、助理橙子
+
+---
+
+## 会议决议
+
+### 1. Redis 缓存接入（已完成）
+
+| 接口 | 路由 | TTL | 失效触发 |
+|------|------|-----|----------|
+| 目录 | `/api/miniprogram/book/parts` | 10min | 章节增删改 |
+| 热门 | `/api/miniprogram/book/hot` | 5min | 章节更新 |
+| 推荐 | `/api/miniprogram/book/recommended` | 5min | 章节更新 |
+| 统计 | `/api/miniprogram/book/stats` | 5min | 章节更新 |
+| 配置 | `/api/miniprogram/config` | 10min | 配置变更 |
+| 正文 | `/api/book/chapter/by-mid/:mid` | 30min | 章节内容更新 |
+
+### 2. Redis 容灾
+
+- Redis 未配置或连接失败时自动回退 DB，不阻塞业务
+- 读写失败仅打日志，不向上抛出
+
+### 3. OSS 上传接入（已完成）
+
+- 管理端图片上传支持阿里云 OSS
+- 未配置或失败时回退本地磁盘
+- 删除支持 OSS URL 与本地路径
+
+### 4. /health 接口增强（已完成）
+
+- 返回 `database`、`redis` 连接状态（ok / disconnected / disabled）
+
+### 5. Redis 配置
+
+- `.env.production`、`.env.development` 增加 REDIS_URL
+- 服务器 Redis：端口 6379，密码 ckb@!（URL 编码 ckb%40%21）
+
+### 6. 迁移功能变更清单（2026-03-17）
+
+1. Redis 缓存接入：目录、热门/推荐/统计、config、章节正文
+2. Redis 容灾：未配置或失败时回退 DB
+3. OSS 上传接入：管理端图片支持阿里云 OSS，容灾回退本地
+4. /health 接口增强：返回 database、redis 连接状态
+5. Redis 配置：.env 增加 REDIS_URL，服务器密码 ckb@!
+6. 文件上传测试：新增 test_upload.py 共 6 个用例
+7. 缓存失效策略：章节/内容/配置变更时自动失效对应 Redis 缓存
+
+---
+
+## 待办事项
+
+| 责任角色 | 任务 | 优先级 | 截止建议 |
+|---------|------|--------|---------|
+| 后端开发 | 部署后验证 Redis 连接（/health 显示 redis: ok） | 中 | 部署后 |
+| 测试人员 | 部署后回归缓存接口（parts、hot、config、章节阅读） | 中 | 部署后 |
+
+---
+
+## 问题与作答区
+
+| # | 问题 | 责任角色 | 作答 |
+|---|------|---------|------|
+| 1 | Redis 与 soul-api 跨机部署时，REDIS_URL 中 host 填 Redis 服务器 IP 是否已文档化？ | 后端开发 | （待补充） |
+
+---
+
+## 各角色经验与业务理解更新
+
+### 后端开发
+
+- internal/cache 包：Get/Set/Del、GetString/SetString；KeyBookParts、KeyChapterContent 等
+- 缓存失效：InvalidateBookParts、InvalidateBookCache、InvalidateConfig、InvalidateChapterContent
+- 章节正文缓存：先查元数据（不含 content），再取 content（Redis 或 DB）
+
+### 管理端开发工程师
+
+- OSS 配置在系统设置保存后，上传接口自动优先 OSS；无需前端改动
+
+### 测试人员
+
+- test_upload.py：6 个用例覆盖上传成功、鉴权、校验、删除
+- /health 可验证 database、redis 连接状态
+
+### 团队共享
+
+- Redis 容灾约定：不可用时回退 DB，不阻塞业务
+- 缓存 key 规范：soul:{业务}:{标识}
+
+---
+
+*会议纪要由助理橙子生成 | 各角色经验已同步至 `agent/{角色}/evolution/2026-03-17.md`*
diff --git a/.cursor/meeting/README.md b/.cursor/meeting/README.md
index 62702b00..7eabb347 100644
--- a/.cursor/meeting/README.md
+++ b/.cursor/meeting/README.md
@@ -78,3 +78,4 @@ YYYY-MM-DD_会议主题.md
 | 2026-03-17 | 新版管理端迁移到稳定版实施方案确认 | 产品、后端、管理端、小程序、测试 | [2026-03-17_新版管理端迁移到稳定版实施方案确认.md](2026-03-17_新版管理端迁移到稳定版实施方案确认.md) |
 | 2026-03-17 | 稳定版源码质量优化方案讨论与开发安排 | 产品、后端、管理端、小程序、测试 | [2026-03-17_稳定版源码质量优化方案讨论与开发安排.md](2026-03-17_稳定版源码质量优化方案讨论与开发安排.md) |
 | 2026-03-17 | 会议收尾：源码优化完成与测试流程定稿 | 产品、后端、管理端、小程序、测试、助理橙子 | [2026-03-17_会议收尾-源码优化完成与测试流程定稿.md](2026-03-17_会议收尾-源码优化完成与测试流程定稿.md) |
+| 2026-03-17 | 性能优化与 Redis 缓存方案落地 | 后端、管理端、小程序、测试、助理橙子 | [2026-03-17_性能优化与Redis缓存方案落地.md](2026-03-17_性能优化与Redis缓存方案落地.md) |
diff --git a/miniprogram/app.js b/miniprogram/app.js
index 12b88878..74bc8bfb 100644
--- a/miniprogram/app.js
+++ b/miniprogram/app.js
@@ -9,8 +9,8 @@ const { checkAndExecute } = require('./utils/ruleEngine.js')
 App({
   globalData: {
     // API 基础地址（切换环境时注释/取消注释）
-    // baseUrl: 'https://soulapi.quwanzhi.com',
-    baseUrl: 'http://localhost:8080',           // 本地调试
+    baseUrl: 'https://soulapi.quwanzhi.com',
+    // baseUrl: 'http://localhost:8080',           // 本地调试
     // baseUrl: 'https://souldev.quwanzhi.com',   // 测试环境
     
     
diff --git a/soul-api/.env.development b/soul-api/.env.development
index 5691c89a..f91d1f32 100644
--- a/soul-api/.env.development
+++ b/soul-api/.env.development
@@ -11,8 +11,11 @@ APP_VERSION=0.0.0
 # 数据库（测试环境 souldev）
 DB_DSN=souldev:RXW2FeRcRdH2GtXy@tcp(56b4c23f6853c.gz.cdb.myqcloud.com:14413)/souldev?charset=utf8mb4&parseTime=True
 
-# Redis（本地 Docker：cd soul-api && docker compose up -d 后启用）
+# Redis
+# 本地开发（无密码）：docker compose up -d 后使用 redis://localhost:6379/0
+# 测试服/服务器（有密码 ckb@!）：redis://:ckb%40%21@localhost:6379/0
 REDIS_URL=redis://localhost:6379/0
+# REDIS_URL=redis://:ckb%40%21@localhost:6379/0
 # 远程库启动时跳过 AutoMigrate（表已存在，避免 information_schema 慢查询）；首次建表时注释掉
 SKIP_AUTO_MIGRATE=1
 # 慢查询阈值(ms)，默认 5000，避免 200ms 刷屏；设为 0 可恢复 GORM 默认
diff --git a/soul-api/.env.production b/soul-api/.env.production
index 84ea08f0..46d6a549 100644
--- a/soul-api/.env.production
+++ b/soul-api/.env.production
@@ -11,6 +11,10 @@ APP_VERSION=0.0.0
 # 数据库（与 Next 现网一致：腾讯云 CDB soul_miniprogram）
 DB_DSN=cdb_outerroot:Zhiqun1984@tcp(56b4c23f6853c.gz.cdb.myqcloud.com:14413)/soul_miniprogram?charset=utf8mb4&parseTime=True
 
+# Redis（服务器实例：端口 6379，密码 ckb@!；同机用 localhost，跨机用 Redis 服务器 IP）
+# 密码含特殊字符需 URL 编码：@ -> %40, ! -> %21
+REDIS_URL=redis://:ckb%40%21@localhost:6379/0
+
 # 统一 API 域名（支付回调、转账回调、apiDomain 等由此派生；无需尾部斜杠）
 API_BASE_URL=https://soulapi.quwanzhi.com
 
diff --git a/soul-api/internal/router/router.go b/soul-api/internal/router/router.go
index db0fa7f2..97a1285d 100644
--- a/soul-api/internal/router/router.go
+++ b/soul-api/internal/router/router.go
@@ -1,9 +1,13 @@
 package router
 
 import (
+	"context"
+
 	"soul-api/internal/config"
+	"soul-api/internal/database"
 	"soul-api/internal/handler"
 	"soul-api/internal/middleware"
+	"soul-api/internal/redis"
 
 	"github.com/gin-contrib/cors"
 	"github.com/gin-gonic/gin"
@@ -372,11 +376,29 @@ func Setup(cfg *config.Config) *gin.Engine {
 		c.Status(204)
 	})
 
-	// 健康检查：返回状态与版本号（版本号从 .env 的 APP_VERSION 读取，打包/上传前写入）
+	// 健康检查：返回状态、版本号、数据库与 Redis 连接状态
 	r.GET("/health", func(c *gin.Context) {
+		dbStatus := "ok"
+		if sqlDB, err := database.DB().DB(); err != nil {
+			dbStatus = "error"
+		} else if err := sqlDB.Ping(); err != nil {
+			dbStatus = "disconnected"
+		}
+
+		redisStatus := "disabled"
+		if redis.Client() != nil {
+			if err := redis.Client().Ping(context.Background()).Err(); err != nil {
+				redisStatus = "disconnected"
+			} else {
+				redisStatus = "ok"
+			}
+		}
+
 		c.JSON(200, gin.H{
 			"status":  "ok",
 			"version": cfg.Version,
+			"database": dbStatus,
+			"redis":    redisStatus,
 		})
 	})
 
diff --git a/开发文档/10、项目管理/运营与变更.md b/开发文档/10、项目管理/运营与变更.md
index cf956bea..323c24d8 100644
--- a/开发文档/10、项目管理/运营与变更.md
+++ b/开发文档/10、项目管理/运营与变更.md
@@ -442,3 +442,28 @@ Mycontent-temp/miniprogram 为样式预览分支，miniprogram 为线上主线
 ## 相关文档
 
 - `.cursor/meeting/2026-03-17_会议收尾-源码优化完成与测试流程定稿.md`
+
+---
+
+# 第十八部分：性能优化与 Redis 缓存方案落地（2026-03-17）
+
+## 会议决议
+
+| 项 | 结论 |
+|----|------|
+| **Redis 缓存** | book/parts、hot、recommended、stats、config、章节 content；TTL 5～30min |
+| **Redis 容灾** | 未配置或连接失败时回退 DB，不阻塞业务 |
+| **OSS 上传** | 管理端图片支持阿里云 OSS，失败回退本地 |
+| **/health** | 返回 database、redis 连接状态 |
+| **配置** | .env 增加 REDIS_URL；服务器 Redis 密码 ckb@! |
+
+## 迁移变更清单
+
+1. Redis 缓存接入：internal/cache 封装，6 类接口缓存
+2. 缓存失效：章节/内容/配置变更时自动失效
+3. OSS 上传：internal/oss 封装，UploadDelete 支持 OSS
+4. test_upload.py：6 个上传/删除用例
+
+## 相关文档
+
+- `.cursor/meeting/2026-03-17_性能优化与Redis缓存方案落地.md`