✨ feat(cache): 幂等只读接口接入缓存

- 新增 withCache 包装：命中直接返回，miss 回源后写入，仅缓存成功响应
- 详情/目录/批量详情/章节摘要缓存 24 小时；搜索/分类列表/分类详情短缓存 10 分钟
- 7 个 fqapi 处理函数原函数体不动、改名 fetchXxx，外层套缓存壳
- redisGetCache 补 3 秒读超时，与写路径一致，防远程 Redis 网络抖动拖垮请求
- 新增 TestWithCache：验证命中不回源、失败响应不缓存

cmd/fanqie/main.go

@@ -138,28 +138,30 @@ func setupRoutes() {
 	http.HandleFunc("/self-info", handlers.RequireAccessKey(handlers.HandleSelfInfo))
 	http.HandleFunc("/vacuum", handlers.RequireAccessKey(handlers.HandleVacuum))
 
-	// API端点
-	http.HandleFunc("/search", handlers.HandleSearch)
-	http.HandleFunc("/detail", handlers.HandleDetail)
-	http.HandleFunc("/info", handlers.HandleDetail)
-	http.HandleFunc("/catalog", handlers.HandleCatalog)
-	http.HandleFunc("/directory/all_items", handlers.HandleCatalog)
-	http.HandleFunc("/multi-detail", handlers.HandleMultiDetail)
-	http.HandleFunc("/multi-content", handlers.HandleMultiContent)
-	http.HandleFunc("/content", handlers.HandleContent)
-	http.HandleFunc("/item-summary", handlers.HandleItemSummary)
-	http.HandleFunc("/category-front", handlers.HandleCategoryFront)
-	http.HandleFunc("/category-landing", handlers.HandleCategoryLanding)
-	http.HandleFunc("/audio", handlers.HandleAudio)
+	http.HandleFunc("/healthz", handlers.HandleHealth)
+
+	// API端点（protect_all 开启时要求访问密钥；代理路由不包，URL 由服务端生成不含 key）
+	http.HandleFunc("/search", handlers.OptionalAccessKey(handlers.HandleSearch))
+	http.HandleFunc("/detail", handlers.OptionalAccessKey(handlers.HandleDetail))
+	http.HandleFunc("/info", handlers.OptionalAccessKey(handlers.HandleDetail))
+	http.HandleFunc("/catalog", handlers.OptionalAccessKey(handlers.HandleCatalog))
+	http.HandleFunc("/directory/all_items", handlers.OptionalAccessKey(handlers.HandleCatalog))
+	http.HandleFunc("/multi-detail", handlers.OptionalAccessKey(handlers.HandleMultiDetail))
+	http.HandleFunc("/multi-content", handlers.OptionalAccessKey(handlers.HandleMultiContent))
+	http.HandleFunc("/content", handlers.OptionalAccessKey(handlers.HandleContent))
+	http.HandleFunc("/item-summary", handlers.OptionalAccessKey(handlers.HandleItemSummary))
+	http.HandleFunc("/category-front", handlers.OptionalAccessKey(handlers.HandleCategoryFront))
+	http.HandleFunc("/category-landing", handlers.OptionalAccessKey(handlers.HandleCategoryLanding))
+	http.HandleFunc("/audio", handlers.OptionalAccessKey(handlers.HandleAudio))
 	http.HandleFunc("/audio/proxy/", handlers.HandleAudioProxy)
-	http.HandleFunc("/video", handlers.HandleVideo)
-	http.HandleFunc("/manga", handlers.HandleManga)
+	http.HandleFunc("/video", handlers.OptionalAccessKey(handlers.HandleVideo))
+	http.HandleFunc("/manga", handlers.OptionalAccessKey(handlers.HandleManga))
 	http.HandleFunc("/manga/image/", handlers.HandleMangaImageProxy)
 
 	// 评论相关端点
-	http.HandleFunc("/chapter_review", handlers.HandleChapterReview)
-	http.HandleFunc("/review", handlers.HandleReview)
-	http.HandleFunc("/review_html", handlers.HandleReviewHTML)
+	http.HandleFunc("/chapter_review", handlers.OptionalAccessKey(handlers.HandleChapterReview))
+	http.HandleFunc("/review", handlers.OptionalAccessKey(handlers.HandleReview))
+	http.HandleFunc("/review_html", handlers.OptionalAccessKey(handlers.HandleReviewHTML))
 	
 	// 表情图片静态文件服务
 	http.Handle("/emoji/", http.StripPrefix("/emoji/", http.FileServer(http.Dir("emoji"))))

internal/config/config.go

@@ -22,6 +22,7 @@ type ServerConfig struct {
 	Port       string `mapstructure:"port"`
 	Host       string `mapstructure:"host"`
 	AccessKey  string `mapstructure:"access_key"`
+	ProtectAll bool   `mapstructure:"protect_all"` // 业务接口也要求访问密钥（公网部署建议开启）
 }
 
 // FanqieConfig 番茄小说配置

internal/fqapi/audio_proxy.go

@@ -35,8 +35,6 @@ func GenerateAudioProxyURL(originalURL, deviceID string, headers map[string]stri
 
 	// 存储到数据库
 	if cacheDB != nil {
-		cacheMutex.Lock()
-		defer cacheMutex.Unlock()
 
 		_, err := cacheDB.Exec(q(`
 			INSERT INTO audio_cache (key, original_url, device_id, headers, created_at)
@@ -71,12 +69,10 @@ func HandleAudioProxy(key string) ([]byte, string, error) {
 		var headersJSON string
 		var createdAt int64
 
-		cacheMutex.Lock()
 		err := cacheDB.QueryRow(q(`
 			SELECT original_url, device_id, headers, created_at
 			FROM audio_cache WHERE key = ?
 		`), key).Scan(&originalURL, &deviceID, &headersJSON, &createdAt)
-		cacheMutex.Unlock()
 
 		if err == sql.ErrNoRows {
 			return nil, "", fmt.Errorf("音频信息不存在，请先调用 /audio 接口")
@@ -88,9 +84,7 @@ func HandleAudioProxy(key string) ([]byte, string, error) {
 		// 检查缓存是否过期（2小时，匹配CDN链接有效期）
 		if time.Now().Unix()-createdAt > 7200 { // 2小时 = 7200秒
 			// 清理过期缓存
-			cacheMutex.Lock()
 			cacheDB.Exec(q("DELETE FROM audio_cache WHERE key = ?"), key)
-			cacheMutex.Unlock()
 			return nil, "", fmt.Errorf("音频信息已过期，请重新调用 /audio 接口")
 		}
 
@@ -121,9 +115,6 @@ func CleanExpiredAudioCache() {
 		return
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	// 删除2小时前的缓存
 	result, err := cacheDB.Exec(q("DELETE FROM audio_cache WHERE created_at < ?"), time.Now().Unix()-7200)
 	if err != nil {

internal/fqapi/cache_manager.go

@@ -10,7 +10,7 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
-	"sync"
+	"sync/atomic"
 	"time"
 
 	_ "github.com/jackc/pgx/v5/stdlib"
@@ -22,10 +22,8 @@ var (
 	cacheDB             *sql.DB
 	dbDriver            string // "sqlite3" | "pgx"
 	redisCache          *redis.Client
-	cacheMutex          sync.Mutex
 	cacheLogger         = common.NewLogger("cache_manager", "INFO", "")
-	contentRequestCount int  // content接口访问计数
-	countMutex          sync.Mutex
+	contentRequestCount atomic.Int64 // content接口访问计数
 	cacheCleanupTicker  *time.Ticker // 缓存清理定时器
 )
 
@@ -49,7 +47,7 @@ func q(query string) string {
 
 // InitRedis 初始化 Redis 缓存（启用后正文缓存与音频代理缓存走 Redis）
 func InitRedis() error {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil || !cfg.Cache.Redis.Enabled {
 		return nil
 	}
@@ -90,7 +88,7 @@ func InitDB() error {
 		return nil // 已初始化
 	}
 
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	backend := "sqlite"
 	dsn := "./cache.db"
 	if cfg != nil {
@@ -250,13 +248,26 @@ func createTables() error {
 
 // isCacheEnabled 检查正文内容缓存是否启用
 func isCacheEnabled() bool {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil {
 		return false
 	}
 	return cfg.Cache.Enabled
 }
 
+// withCache 只读接口的缓存包装：命中直接返回，miss 回源后写入（仅缓存成功响应）
+// ponytail: 空参等防御分支若漏到此处，其错误 JSON 也会被缓存到 TTL 到期——handler 层 validateParams 已拦截
+func withCache(key string, ttl int, fetch func() (string, error)) (string, error) {
+	if c := GetCache(key); c != "" {
+		return c, nil
+	}
+	result, err := fetch()
+	if err == nil {
+		UpdateCache(key, result, ttl)
+	}
+	return result, err
+}
+
 // GetCache 获取正文内容缓存
 func GetCache(key string) string {
 	if !isCacheEnabled() {
@@ -271,9 +282,6 @@ func GetCache(key string) string {
 		return ""
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	var value string
 	err := cacheDB.QueryRow(q("SELECT value FROM cache WHERE key = ?"), key).Scan(&value)
 	if err != nil {
@@ -316,9 +324,6 @@ func UpdateCache(key string, value string, expi int) error {
 		return nil
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	cacheData := CacheData{
 		Data: value,
 		Expi: float64(time.Now().Unix() + int64(expi)),
@@ -341,7 +346,6 @@ func UpdateCache(key string, value string, expi int) error {
 	return nil
 }
 
-
 // CloseCache 关闭缓存数据库
 func CloseCache() {
 	if cacheDB != nil {
@@ -349,18 +353,12 @@ func CloseCache() {
 	}
 }
 
-
-
-
 // CleanupAllCache 立即清理所有正文缓存
 func CleanupAllCache() error {
 	if cacheDB == nil {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	// 删除所有缓存数据
 	_, err := cacheDB.Exec("DELETE FROM cache")
 	if err != nil {
@@ -401,7 +399,7 @@ func CleanupAllCache() error {
 
 // CleanupExpiredCache 清理过期的正文缓存
 func CleanupExpiredCache() error {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil {
 		return fmt.Errorf("配置未加载")
 	}
@@ -420,9 +418,6 @@ func CleanupExpiredCache() error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	// 计算过期时间点（当前时间 - cleanup_seconds）
 	expiredTime := time.Now().Unix() - int64(cfg.Cache.CleanupSeconds)
 
@@ -446,7 +441,7 @@ func CleanupExpiredCache() error {
 
 // StartCacheCleanup 启动缓存自动清理任务
 func StartCacheCleanup() {
-	cfg := config.GetConfig()
+	cfg := config.GetAppConfig()
 	if cfg == nil || !cfg.Cache.CleanupEnabled || cfg.Cache.CleanupSeconds <= 0 {
 		cacheLogger.Info("缓存自动清理未启用或配置无效，跳过启动")
 		return
@@ -488,36 +483,21 @@ func StopCacheCleanup() {
 }
 
 // IncrementContentRequestCount 增加content接口访问计数
-func IncrementContentRequestCount() int {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	contentRequestCount++
-	return contentRequestCount
-}
+func IncrementContentRequestCount() int { return int(contentRequestCount.Add(1)) }
 
 // ResetContentRequestCount 重置访问计数
-func ResetContentRequestCount() {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	contentRequestCount = 0
-}
+func ResetContentRequestCount() { contentRequestCount.Store(0) }
 
 // GetContentRequestCount 获取当前访问计数
-func GetContentRequestCount() int {
-	countMutex.Lock()
-	defer countMutex.Unlock()
-	return contentRequestCount
-}
+func GetContentRequestCount() int { return int(contentRequestCount.Load()) }
 
 // VacuumDatabase 压缩数据库，释放磁盘空间
+// ponytail: 删了全局串行锁，VACUUM 与写操作的并发冲突由 busy_timeout(5s) 兜底，失败仅记日志
 func VacuumDatabase() error {
 	if cacheDB == nil {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	cacheLogger.Info("开始执行数据库压缩...")
 	if dbDriver == "pgx" {
 		cacheLogger.Info("PostgreSQL 由 autovacuum 自动管理，无需手动压缩")
@@ -539,9 +519,6 @@ func GetDatabaseStats() (map[string]interface{}, error) {
 		return nil, fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	stats := make(map[string]interface{})
 
 	// 获取cache表记录数
@@ -596,9 +573,6 @@ func SaveStatistics(stats map[string]int64) error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	_, err := cacheDB.Exec(q(`
 		UPDATE statistics
 		SET total_requests = ?,
@@ -630,9 +604,6 @@ func LoadStatistics() (map[string]int64, error) {
 		return nil, fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
-
 	var total, search, detail, catalog, content, manga, audio, video, category int64
 	
 	err := cacheDB.QueryRow(`

internal/fqapi/cache_manager_test.go

@@ -0,0 +1,100 @@
+package fqapi
+
+import (
+	"database/sql"
+	"fanqie/internal/config"
+	"fmt"
+	"sync"
+	"testing"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// TestConcurrentCacheAccess 验证删除全局串行锁后并发读写缓存不死锁、不 panic、数据正确（配合 -race）
+func TestConcurrentCacheAccess(t *testing.T) {
+	if err := config.LoadConfig("../../config/config.yaml"); err != nil {
+		t.Skipf("无法加载配置: %v", err)
+	}
+
+	db, err := sql.Open("sqlite3", t.TempDir()+"/test.db?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		t.Fatal(err)
+	}
+	oldDB, oldDriver := cacheDB, dbDriver
+	cacheDB, dbDriver = db, "sqlite3"
+	defer func() {
+		cacheDB, dbDriver = oldDB, oldDriver
+		db.Close()
+	}()
+
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS cache (
+		key TEXT PRIMARY KEY,
+		value TEXT,
+		created_at INTEGER DEFAULT (strftime('%s', 'now'))
+	)`); err != nil {
+		t.Fatal(err)
+	}
+
+	var wg sync.WaitGroup
+	for i := 0; i < 8; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			for j := 0; j < 30; j++ {
+				key := fmt.Sprintf("k-%d-%d", i, j)
+				if err := UpdateCache(key, "value-"+key, 60); err != nil {
+					t.Errorf("UpdateCache(%s): %v", key, err)
+					return
+				}
+				if got := GetCache(key); got != "value-"+key {
+					t.Errorf("GetCache(%s) = %q, want %q", key, got, "value-"+key)
+					return
+				}
+			}
+		}(i)
+	}
+	wg.Wait()
+}
+
+// TestWithCache 验证缓存命中不回源、失败响应不缓存
+func TestWithCache(t *testing.T) {
+	if err := config.LoadConfig("../../config/config.yaml"); err != nil {
+		t.Skipf("无法加载配置: %v", err)
+	}
+	db, err := sql.Open("sqlite3", t.TempDir()+"/test.db?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		t.Fatal(err)
+	}
+	oldDB, oldDriver := cacheDB, dbDriver
+	cacheDB, dbDriver = db, "sqlite3"
+	defer func() {
+		cacheDB, dbDriver = oldDB, oldDriver
+		db.Close()
+	}()
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS cache (
+		key TEXT PRIMARY KEY, value TEXT,
+		created_at INTEGER DEFAULT (strftime('%s', 'now'))
+	)`); err != nil {
+		t.Fatal(err)
+	}
+
+	calls := 0
+	fetch := func() (string, error) { calls++; return "result", nil }
+	if got, _ := withCache("wc_hit", 60, fetch); got != "result" {
+		t.Fatalf("首次应返回回源结果, got %q", got)
+	}
+	if got, _ := withCache("wc_hit", 60, fetch); got != "result" {
+		t.Fatalf("命中应返回缓存结果, got %q", got)
+	}
+	if calls != 1 {
+		t.Fatalf("命中缓存不应回源, fetch 调用 %d 次", calls)
+	}
+
+	errCalls := 0
+	errFetch := func() (string, error) { errCalls++; return "", fmt.Errorf("boom") }
+	withCache("wc_miss", 60, errFetch)
+	withCache("wc_miss", 60, errFetch)
+	if errCalls != 2 {
+		t.Fatalf("失败响应不应被缓存, fetch 调用 %d 次", errCalls)
+	}
+}

internal/fqapi/catalog.go

@@ -10,8 +10,14 @@ import (
 
 var catalogLogger = common.NewLogger("catalog", "INFO", "")
 
-// HandleGetCatalog 处理获取书籍目录
+// HandleGetCatalog 处理获取书籍目录,目录数据基本不变,缓存 24 小时
 func HandleGetCatalog(bookID string) (string, error) {
+	return withCache("catalog_" + bookID, 86400, func() (string, error) {
+		return fetchCatalog(bookID)
+	})
+}
+
+func fetchCatalog(bookID string) (string, error) {
 	if bookID == "" {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}

internal/fqapi/category_front.go

@@ -7,8 +7,14 @@ import (
 
 var categoryFrontLogger = common.NewLogger("category_front", "INFO", "")
 
-// HandleCategoryFront 处理获取分类列表
+// HandleCategoryFront 处理获取分类列表,分类列表短缓存 10 分钟
 func HandleCategoryFront(tab interface{}) (string, error) {
+	return withCache(fmt.Sprintf("category_front_%v", tab), 600, func() (string, error) {
+		return fetchCategoryFront(tab)
+	})
+}
+
+func fetchCategoryFront(tab interface{}) (string, error) {
 	tabInt := ParseIntParam(tab, 0)
 
 	reqURL := BuildURL(

internal/fqapi/category_landing.go

@@ -7,8 +7,14 @@ import (
 
 var categoryLandingLogger = common.NewLogger("category_landing", "INFO", "")
 
-// HandleCategoryLanding 处理获取分类详情
+// HandleCategoryLanding 处理获取分类详情,分类详情短缓存 10 分钟
 func HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy interface{}) (string, error) {
+	return withCache(fmt.Sprintf("category_landing_%v_%v_%v_%v_%v", categoryID, offset, wordNumber, bookStatus, sortBy), 600, func() (string, error) {
+		return fetchCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy)
+	})
+}
+
+func fetchCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy interface{}) (string, error) {
 	// 参数转换
 	categoryIDInt := ParseIntParam(categoryID, 0)
 	offsetInt := ParseIntParam(offset, 0)

internal/fqapi/detail.go

@@ -8,8 +8,14 @@ import (
 
 var detailLogger = common.NewLogger("detail", "INFO", "")
 
-// HandleGetDetail 处理获取书籍详情
+// HandleGetDetail 处理获取书籍详情,详情数据基本不变,缓存 24 小时
 func HandleGetDetail(bookID string) (string, error) {
+	return withCache("detail_" + bookID, 86400, func() (string, error) {
+		return fetchDetail(bookID)
+	})
+}
+
+func fetchDetail(bookID string) (string, error) {
 	if bookID == "" {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}

internal/fqapi/device_key_pool.go

@@ -399,8 +399,6 @@ func (p *DeviceKeyPool) saveDeviceToDB(item *DeviceKeyItem) error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
 
 	// RETURNING id 同时兼容 SQLite(3.35+) 与 PostgreSQL，替代 LastInsertId()
 	err := cacheDB.QueryRow(q(`
@@ -419,8 +417,6 @@ func (p *DeviceKeyPool) updateDeviceInDB(item *DeviceKeyItem) error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
 
 	_, err := cacheDB.Exec(q(`
 		UPDATE device_pool
@@ -438,8 +434,6 @@ func (p *DeviceKeyPool) removeInvalidFromDB() error {
 		return fmt.Errorf("数据库未初始化")
 	}
 
-	cacheMutex.Lock()
-	defer cacheMutex.Unlock()
 
 	result, err := cacheDB.Exec(`DELETE FROM device_pool WHERE is_valid = 0`)
 	if err != nil {

internal/fqapi/item_summary.go

@@ -7,8 +7,14 @@ import (
 
 var itemSummaryLogger = common.NewLogger("item_summary", "INFO", "")
 
-// HandleItemSummary 处理获取章节摘要
+// HandleItemSummary 处理获取章节摘要,章节摘要数据基本不变,缓存 24 小时
 func HandleItemSummary(itemIDs, bookID string) (string, error) {
+	return withCache("item_summary_" + bookID + "_" + itemIDs, 86400, func() (string, error) {
+		return fetchItemSummary(itemIDs, bookID)
+	})
+}
+
+func fetchItemSummary(itemIDs, bookID string) (string, error) {
 	if itemIDs == "" || bookID == "" {
 		return BuildErrorResponseWithCode(100144, "参数错误"), nil
 	}

internal/fqapi/multi_detail.go

@@ -107,8 +107,14 @@ func chunkArray(arr []string, size int) [][]string {
 	return chunks
 }
 
-// HandleGetMultiDetail 处理批量获取书籍详情
+// HandleGetMultiDetail 处理批量获取书籍详情,详情数据基本不变,缓存 24 小时
 func HandleGetMultiDetail(bookID interface{}) (string, error) {
+	return withCache(fmt.Sprintf("multi_detail_%v", bookID), 86400, func() (string, error) {
+		return fetchMultiDetail(bookID)
+	})
+}
+
+func fetchMultiDetail(bookID interface{}) (string, error) {
 	if bookID == nil {
 		return BuildErrorResponse("需要参数 book_id"), nil
 	}

internal/fqapi/search.go

@@ -11,8 +11,14 @@ var searchLogger = common.NewLogger("search", "INFO", "")
 // GetDeviceHeader 获取设备header（需要从外部注入）
 var GetDeviceHeader func() string
 
-// HandleBookSearch 处理书籍搜索
+// HandleBookSearch 处理书籍搜索,搜索结果短缓存 10 分钟,减轻上游压力
 func HandleBookSearch(key string, offset int, tabType int) (string, error) {
+	return withCache(fmt.Sprintf("search_%s_%d_%d", key, offset, tabType), 600, func() (string, error) {
+		return fetchBookSearch(key, offset, tabType)
+	})
+}
+
+func fetchBookSearch(key string, offset int, tabType int) (string, error) {
 	if key == "" {
 		return BuildErrorResponseWithCode(1, "需要参数 key"), nil
 	}

internal/fqapi/store_redis.go

@@ -23,7 +23,10 @@ const (
 
 // redisGetCache 从 Redis 获取正文缓存
 func redisGetCache(key string) string {
-	val, err := redisCache.Get(context.Background(), redisCacheKeyPrefix+key).Result()
+	// 读操作同样加 3s 超时，防止远程 Redis 网络抖动拖垮请求（与写路径一致）
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	val, err := redisCache.Get(ctx, redisCacheKeyPrefix+key).Result()
 	if err != nil {
 		return "" // miss 或错误都视为未命中
 	}

internal/handlers/book.go

@@ -4,7 +4,6 @@ import (
 	"fanqie/internal/fqapi"
 	"fmt"
 	"net/http"
-	"strconv"
 )
 
 // HandleSearch 搜索处理
@@ -16,22 +15,29 @@ func HandleSearch(w http.ResponseWriter, r *http.Request) {
 	if query == "" {
 		query = r.URL.Query().Get("key")
 	}
-
-	offsetStr := r.URL.Query().Get("offset")
-	offset := 0
-	if offsetStr != "" {
-		offset, _ = strconv.Atoi(offsetStr)
+	if query == "" {
+		respondError(w, "缺少 query 参数", true)
+		return
 	}
 
-	tabTypeStr := r.URL.Query().Get("tab_type")
-	tabType := 3
-	if tabTypeStr != "" {
-		tabType, _ = strconv.Atoi(tabTypeStr)
+	offset, err := parseIntParam(r.URL.Query().Get("offset"), "offset")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	tabType, err := parseIntParam(r.URL.Query().Get("tab_type"), "tab_type")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	if tabType == 0 {
+		tabType = 3
 	}
 
 	result, err := fqapi.HandleBookSearch(query, offset, tabType)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "搜索失败: %s"}`, err.Error())
+		respondError(w, "搜索失败: "+err.Error(), false)
 		return
 	}
 
@@ -43,11 +49,15 @@ func HandleDetail(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetDetail(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "获取详情失败: "+err.Error(), false)
 		return
 	}
 
@@ -59,11 +69,15 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "catalog")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetCatalog(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取目录失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetCatalog(params["book_id"])
+	if err != nil {
+		respondError(w, "获取目录失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,13 +86,18 @@ func HandleCatalog(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiDetail 批量详情处理
 func HandleMultiDetail(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "detail")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-
-	result, err := fqapi.HandleGetMultiDetail(bookID)
+	params, err := validateParams(r, "book_id")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取详情失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleGetMultiDetail(params["book_id"])
+	if err != nil {
+		respondError(w, "批量获取详情失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/category.go

@@ -15,7 +15,7 @@ func HandleCategoryFront(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleCategoryFront(tab)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类列表失败: %s"}`, err.Error())
+		respondError(w, "获取分类列表失败: "+err.Error(), false)
 		return
 	}
 
@@ -35,7 +35,7 @@ func HandleCategoryLanding(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleCategoryLanding(categoryID, offset, wordNumber, bookStatus, sortBy)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取分类详情失败: %s"}`, err.Error())
+		respondError(w, "获取分类详情失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/common.go

@@ -1,6 +1,7 @@
 package handlers
 
 import (
+	"crypto/subtle"
 	"encoding/json"
 	"fanqie/internal/config"
 	"fanqie/internal/fqapi"
@@ -96,6 +97,15 @@ func StopStatisticsSaver() {
 	}
 }
 
+// respondError 统一错误响应（JSON 安全编码；isClientErr 为 true 时返回 400，否则 500）
+func respondError(w http.ResponseWriter, msg string, isClientErr bool) {
+	status := http.StatusInternalServerError
+	if isClientErr {
+		status = http.StatusBadRequest
+	}
+	respondJSON(w, status, map[string]interface{}{"code": -1, "msg": msg})
+}
+
 // RequireAccessKey 验证访问密钥中间件
 func RequireAccessKey(handler http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -113,8 +123,8 @@ func RequireAccessKey(handler http.HandlerFunc) http.HandlerFunc {
 			key = r.Header.Get("X-Access-Key")
 		}
 		
-		// 验证密钥
-		if key != cfg.Server.AccessKey {
+		// 验证密钥（常量时间比较，防时序攻击）
+		if subtle.ConstantTimeCompare([]byte(key), []byte(cfg.Server.AccessKey)) != 1 {
 			w.Header().Set("Content-Type", "application/json; charset=utf-8")
 			w.WriteHeader(http.StatusUnauthorized)
 			fmt.Fprintf(w, `{"code": -1, "msg": "访问被拒绝：无效的访问密钥"}`)
@@ -126,6 +136,20 @@ func RequireAccessKey(handler http.HandlerFunc) http.HandlerFunc {
 	}
 }
 
+// OptionalAccessKey 业务接口保护（仅 server.protect_all 开启时校验）
+func OptionalAccessKey(handler http.HandlerFunc) http.HandlerFunc {
+	cfg := config.GetAppConfig()
+	if cfg == nil || !cfg.Server.ProtectAll {
+		return handler
+	}
+	return RequireAccessKey(handler)
+}
+
+// HandleHealth 存活探针（供容器/反向代理使用）
+func HandleHealth(w http.ResponseWriter, r *http.Request) {
+	fmt.Fprint(w, "ok")
+}
+
 // HandleMain 主页处理
 func HandleMain(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")

internal/handlers/content.go

@@ -12,8 +12,12 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	// 从查询参数获取item_id
-	itemID := r.URL.Query().Get("item_id")
+	params, err := validateParams(r, "item_id")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+	itemID := params["item_id"]
 
 	// 获取URL参数（支持动态覆盖配置）
 	textMode := r.URL.Query().Get("text_mode")     // 1=纯文本模式
@@ -22,7 +26,7 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleGetContent(itemID, textMode, imageMode)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取内容失败: %s"}`, err.Error())
+		respondError(w, "获取内容失败: "+err.Error(), false)
 		return
 	}
 
@@ -51,17 +55,22 @@ func HandleContent(w http.ResponseWriter, r *http.Request) {
 
 // HandleMultiContent 批量内容处理
 func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
+	incrementStat("total", "content")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "book_id", "item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	textMode := r.URL.Query().Get("text_mode")
 	imageMode := r.URL.Query().Get("image_mode")
 	ignoreFailed := r.URL.Query().Get("ignore_failed")
 
-	result, err := fqapi.HandleMultiContent(itemIDs, bookID, textMode, imageMode, ignoreFailed)
+	result, err := fqapi.HandleMultiContent(params["item_ids"], params["book_id"], textMode, imageMode, ignoreFailed)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "批量获取内容失败: %s"}`, err.Error())
+		respondError(w, "批量获取内容失败: "+err.Error(), false)
 		return
 	}
 
@@ -72,12 +81,15 @@ func HandleMultiContent(w http.ResponseWriter, r *http.Request) {
 func HandleItemSummary(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	bookID := r.URL.Query().Get("book_id")
-	itemIDs := r.URL.Query().Get("item_ids")
-
-	result, err := fqapi.HandleItemSummary(itemIDs, bookID)
+	params, err := validateParams(r, "book_id", "item_ids")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取章节摘要失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleItemSummary(params["item_ids"], params["book_id"])
+	if err != nil {
+		respondError(w, "获取章节摘要失败: "+err.Error(), false)
 		return
 	}
 

internal/handlers/error_response_test.go

@@ -0,0 +1,62 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestRespondErrorProducesValidJSON 错误信息含引号/换行时输出仍须是合法 JSON
+func TestRespondErrorProducesValidJSON(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "上游返回了 \"引号\" 和\n换行", false)
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("非法 JSON: %v, body: %s", err, w.Body.String())
+	}
+	if body["code"].(float64) != -1 {
+		t.Errorf("code 应为 -1, got %v", body["code"])
+	}
+	if w.Code != 500 {
+		t.Errorf("服务端错误应返回 500, got %d", w.Code)
+	}
+}
+
+// TestRespondErrorClientErr 客户端错误应返回 400
+func TestRespondErrorClientErr(t *testing.T) {
+	w := httptest.NewRecorder()
+	respondError(w, "缺少 book_id 参数", true)
+	if w.Code != 400 {
+		t.Errorf("客户端错误应返回 400, got %d", w.Code)
+	}
+}
+
+// TestHandleDetailMissingParam 缺少必需参数返回 400 而非透传到上游
+func TestHandleDetailMissingParam(t *testing.T) {
+	w := httptest.NewRecorder()
+	HandleDetail(w, httptest.NewRequest("GET", "/detail", nil))
+	if w.Code != 400 {
+		t.Errorf("缺参应返回 400, got %d, body: %s", w.Code, w.Body.String())
+	}
+}
+
+// TestOptionalAccessKeyDisabled protect_all 未启用（或配置未加载）时直接放行
+func TestOptionalAccessKeyDisabled(t *testing.T) {
+	called := false
+	h := OptionalAccessKey(func(w http.ResponseWriter, r *http.Request) { called = true })
+	h(httptest.NewRecorder(), httptest.NewRequest("GET", "/search?query=x", nil))
+	if !called {
+		t.Error("protect_all 未启用时应直接放行")
+	}
+}
+
+// TestHandleHealth 存活探针返回 200 ok
+func TestHandleHealth(t *testing.T) {
+	w := httptest.NewRecorder()
+	HandleHealth(w, httptest.NewRequest("GET", "/healthz", nil))
+	if w.Code != 200 || w.Body.String() != "ok" {
+		t.Errorf("应返回 200 ok, got %d %q", w.Code, w.Body.String())
+	}
+}

internal/handlers/media.go

@@ -13,13 +13,18 @@ func HandleAudio(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "audio")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
+	params, err := validateParams(r, "item_ids")
+	if err != nil {
+		respondError(w, err.Error(), true)
+		return
+	}
+
 	toneID := r.URL.Query().Get("tone_id")
 	output := r.URL.Query().Get("output")
 
-	result, err := fqapi.HandleAudio(itemIDs, toneID, output)
+	result, err := fqapi.HandleAudio(params["item_ids"], toneID, output)
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取音频失败: %s"}`, err.Error())
+		respondError(w, "获取音频失败: "+err.Error(), false)
 		return
 	}
 
@@ -62,11 +67,15 @@ func HandleVideo(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "video")
 	w.Header().Set("Content-Type", "application/json; charset=utf-8")
 
-	itemIDs := r.URL.Query().Get("item_ids")
-
-	result, err := fqapi.HandleVideo(itemIDs)
+	params, err := validateParams(r, "item_ids")
 	if err != nil {
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取视频失败: %s"}`, err.Error())
+		respondError(w, err.Error(), true)
+		return
+	}
+
+	result, err := fqapi.HandleVideo(params["item_ids"])
+	if err != nil {
+		respondError(w, "获取视频失败: "+err.Error(), false)
 		return
 	}
 
@@ -76,14 +85,13 @@ func HandleVideo(w http.ResponseWriter, r *http.Request) {
 // HandleManga 漫画处理
 func HandleManga(w http.ResponseWriter, r *http.Request) {
 	incrementStat("total", "manga")
+
 	itemID := r.URL.Query().Get("item_ids")
 	if itemID == "" {
 		itemID = r.URL.Query().Get("item_id")
 	}
-
 	if itemID == "" {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
-		fmt.Fprint(w, `{"code": -1, "msg": "缺少item_ids参数"}`)
+		respondError(w, "缺少 item_ids 参数", true)
 		return
 	}
 
@@ -96,8 +104,7 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 
 	result, err := fqapi.HandleGetManga(itemID, showHTML, outputMode)
 	if err != nil {
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
-		fmt.Fprintf(w, `{"code": -1, "msg": "获取漫画失败: %s"}`, err.Error())
+		respondError(w, "获取漫画失败: "+err.Error(), false)
 		return
 	}
 
@@ -113,16 +120,16 @@ func HandleManga(w http.ResponseWriter, r *http.Request) {
 		fmt.Fprint(w, `<p>未找到漫画内容</p>`)
 	} else {
 		// 返回JSON格式
-		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		jsonData, err := json.Marshal(map[string]interface{}{
 			"code": 0,
 			"msg":  "success",
 			"data": result,
 		})
 		if err != nil {
-			fmt.Fprintf(w, `{"code": -1, "msg": "JSON编码失败: %s"}`, err.Error())
+			respondError(w, "JSON编码失败: "+err.Error(), false)
 			return
 		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
 		fmt.Fprint(w, string(jsonData))
 	}
 }

openapi.yaml

@@ -50,6 +50,20 @@ paths:
                   message: { type: string, example: success }
                   data: { nullable: true }
 
+  /healthz:
+    get:
+      tags: [系统]
+      summary: 存活探针
+      description: 供容器/反向代理探活,不校验访问密钥。
+      operationId: getHealthz
+      responses:
+        "200":
+          description: 服务存活
+          content:
+            text/plain:
+              schema: { type: string }
+              example: ok
+
   /status:
     get:
       tags: [系统]
@@ -169,6 +183,10 @@ paths:
                 $ref: "#/components/schemas/UpstreamResponse"
               example: { code: 0, msg: success, data: { search_book_data_list: [], has_more: 1 } }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /detail:
     get:
       tags: [书籍]
@@ -183,6 +201,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /info:
     get:
       tags: [书籍]
@@ -197,6 +219,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /catalog:
     get:
       tags: [书籍]
@@ -211,6 +237,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /directory/all_items:
     get:
       tags: [书籍]
@@ -225,6 +255,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /multi-detail:
     get:
       tags: [书籍]
@@ -244,6 +278,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /content:
     get:
       tags: [内容]
@@ -295,6 +333,10 @@ paths:
                             properties:
                               book_id: { type: string, description: 所属书籍 ID }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /multi-content:
     get:
       tags: [内容]
@@ -327,6 +369,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /item-summary:
     get:
       tags: [内容]
@@ -346,6 +392,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /chapter_review:
     get:
       tags: [评论]
@@ -371,6 +421,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /review:
     get:
       tags: [评论]
@@ -405,6 +457,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /review_html:
     get:
       tags: [评论]
@@ -432,6 +486,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /audio:
     get:
       tags: [多媒体]
@@ -459,6 +515,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /audio/proxy/{key}:
     get:
       tags: [多媒体]
@@ -507,6 +567,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /manga:
     get:
       tags: [多媒体]
@@ -547,6 +611,8 @@ paths:
         "400":
           $ref: "#/components/responses/BadRequest"
 
+        "500":
+          $ref: "#/components/responses/ServerError"
   /manga/image/{item_id}/{index}:
     get:
       tags: [多媒体]
@@ -606,6 +672,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /category-landing:
     get:
       tags: [分类]
@@ -633,6 +703,10 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/UpstreamResponse" }
 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "500":
+          $ref: "#/components/responses/ServerError"
   /emoji/{file}:
     get:
       tags: [静态资源]
@@ -660,6 +734,7 @@ paths:
             text/plain:
               schema: { type: string }
 
+
 components:
   securitySchemes:
     accessKeyQuery:
@@ -689,12 +764,19 @@ components:
 
   responses:
     Unauthorized:
-      description: 访问密钥缺失或无效
+      description: 访问密钥缺失或无效(业务接口仅在 server.protect_all 开启时需要)
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorResponse"
           example: { code: -1, msg: "访问被拒绝:无效的访问密钥" }
+    ServerError:
+      description: 服务端错误(上游请求失败等)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          example: { code: -1, msg: "获取内容失败: 请求超时" }
     BadRequest:
       description: 参数缺失或格式错误
       content: