feat(log): 解耦用户访问日志存储，支持切换日志主库

用户访问日志可在 ClickHouse、PostgreSQL、SQLite 之间切换。关闭 ClickHouse 时由主库承接写入与查询；切换任务会冻结写入、复制数据后翻转主库。启动时校验日志主库与运行配置一致，定期清理按各库保留天数删除过期记录。
2026-10-07 08:06:37 +08:00 · 2026-08-16 11:17:55 +08:00
parent 6a53619dd2
commit e52592b16d
34 changed files with 2325 additions and 145 deletions
@@ -40,23 +40,6 @@ definitions:
    - max_size_mb
    - ttl_minutes
    type: object
-  cap.ChallengeResponse:
-    properties:
-      challenge:
-        properties:
-          c:
-            type: integer
-          d:
-            type: integer
-          s:
-            type: integer
-        type: object
-      expires:
-        description: ms timestamp
-        type: integer
-      token:
-        type: string
-    type: object
  cap.challengeRequest:
    properties:
      scope:
@@ -132,6 +115,23 @@ definitions:
      ttl_minutes:
        type: integer
    type: object
+  github_com_Rain-kl_Wavelet_internal_apps_cap.ChallengeResponse:
+    properties:
+      challenge:
+        properties:
+          c:
+            type: integer
+          d:
+            type: integer
+          s:
+            type: integer
+        type: object
+      expires:
+        description: ms timestamp
+        type: integer
+      token:
+        type: string
+    type: object
  github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse:
    properties:
      error:
@@ -949,6 +949,21 @@ definitions:
      version:
        type: string
    type: object
+  status.LogDatabaseStatus:
+    properties:
+      active_database:
+        type: string
+      available_targets:
+        items:
+          type: string
+        type: array
+      migration:
+        type: string
+      retention_days:
+        additionalProperties:
+          type: integer
+        type: object
+    type: object
  status.SystemStatusResponse:
    properties:
      alloc:
@@ -1358,6 +1373,23 @@ definitions:
      website:
        type: string
    type: object
+  user.updateUserRequest:
+    properties:
+      email:
+        maxLength: 255
+        type: string
+      is_admin:
+        type: boolean
+      nickname:
+        maxLength: 64
+        type: string
+      password:
+        maxLength: 64
+        minLength: 8
+        type: string
+    required:
+    - email
+    type: object
  user.updateUserStatusRequest:
    properties:
      is_active:
@@ -1425,11 +1457,16 @@ paths:
        "200":
          description: 成功返回 PoW 难题
          schema:
-            $ref: '#/definitions/cap.ChallengeResponse'
+            allOf:
+            - $ref: '#/definitions/response.Any'
+            - properties:
+                data:
+                  $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.ChallengeResponse'
+              type: object
        "500":
          description: 内部服务错误
          schema:
-            $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse'
+            $ref: '#/definitions/response.Any'
      summary: 生成人机验证难题
      tags:
      - cap
@@ -1451,15 +1488,20 @@ paths:
        "200":
          description: 核销成功，返回 X-Cap-Token
          schema:
-            $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse'
+            allOf:
+            - $ref: '#/definitions/response.Any'
+            - properties:
+                data:
+                  $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse'
+              type: object
        "400":
          description: 参数错误或核销失败
          schema:
-            $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse'
+            $ref: '#/definitions/response.Any'
        "500":
          description: 内部服务错误
          schema:
-            $ref: '#/definitions/github_com_Rain-kl_Wavelet_internal_apps_cap.RedeemResponse'
+            $ref: '#/definitions/response.Any'
      summary: 校验人机验证解答
      tags:
      - cap
@@ -1997,7 +2039,7 @@ paths:
      - admin
  /api/v1/admin/logs/access:
    get:
-      description: 分页并按照用户、接口路径、时间范围等维度检索 ClickHouse 用户访问日志列表（需要管理员权限，ClickHouse 未启用时报错）
+      description: 分页并按照用户、接口路径、时间范围等维度检索用户访问日志列表（需要管理员权限）
      parameters:
      - default: 1
        description: 页码
@@ -2038,7 +2080,7 @@ paths:
                  $ref: '#/definitions/logs.accessLogsResponse'
              type: object
        "400":
-          description: ClickHouse 未启用或参数错误
+          description: 参数错误
          schema:
            $ref: '#/definitions/response.Any'
        "401":
@@ -2049,6 +2091,10 @@ paths:
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
+        "500":
+          description: 内部错误
+          schema:
+            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取用户访问日志
@@ -2056,7 +2102,7 @@ paths:
      - admin
  /api/v1/admin/logs/analytics:
    get:
-      description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限，ClickHouse 未启用时报错）
+      description: 聚合统计最近 7 天的每日访问趋势、浏览器分布以及前 10 名最活跃用户排行（需要管理员权限）
      produces:
      - application/json
      responses:
@@ -2069,10 +2115,6 @@ paths:
                data:
                  $ref: '#/definitions/logs.logsAnalyticsResponse'
              type: object
-        "400":
-          description: ClickHouse 未启用
-          schema:
-            $ref: '#/definitions/response.Any'
        "401":
          description: 未登录
          schema:
@@ -2081,6 +2123,10 @@ paths:
          description: 无管理员权限
          schema:
            $ref: '#/definitions/response.Any'
+        "500":
+          description: 内部错误
+          schema:
+            $ref: '#/definitions/response.Any'
      security:
      - SessionCookie: []
      summary: 获取访问日志分析数据
@@ -2496,6 +2542,38 @@ paths:
      summary: 获取系统状态信息
      tags:
      - admin
+  /api/v1/admin/status/log-database:
+    get:
+      description: 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 获取成功
+          schema:
+            allOf:
+            - $ref: '#/definitions/response.Any'
+            - properties:
+                data:
+                  $ref: '#/definitions/status.LogDatabaseStatus'
+              type: object
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/response.Any'
+        "403":
+          description: 无管理员权限
+          schema:
+            $ref: '#/definitions/response.Any'
+        "500":
+          description: 内部错误
+          schema:
+            $ref: '#/definitions/response.Any'
+      security:
+      - SessionCookie: []
+      summary: 获取日志数据库状态
+      tags:
+      - admin
  /api/v1/admin/system-configs:
    get:
      description: 返回所有系统配置列表，支持按配置类型（system/business）过滤，需要管理员权限
@@ -3589,6 +3667,9 @@ paths:
    get:
      description: 分页返回用户列表，支持按用户 ID 和用户名筛选，需要管理员权限
      parameters:
+      - in: query
+        name: email
+        type: string
      - in: query
        minimum: 1
        name: page
@@ -3772,6 +3853,59 @@ paths:
      summary: 获取用户详情
      tags:
      - admin
+    put:
+      consumes:
+      - application/json
+      description: 更新指定用户的昵称、邮箱、管理员权限，并可选重置密码，需要管理员权限
+      parameters:
+      - description: 用户 ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      - description: 更新参数
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/user.updateUserRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 更新成功
+          schema:
+            allOf:
+            - $ref: '#/definitions/response.Any'
+            - properties:
+                data:
+                  type: string
+              type: object
+        "400":
+          description: 参数错误
+          schema:
+            $ref: '#/definitions/response.Any'
+        "401":
+          description: 未登录
+          schema:
+            $ref: '#/definitions/response.Any'
+        "403":
+          description: 无管理员权限或尝试修改自身权限
+          schema:
+            $ref: '#/definitions/response.Any'
+        "404":
+          description: 用户不存在
+          schema:
+            $ref: '#/definitions/response.Any'
+        "500":
+          description: 内部错误
+          schema:
+            $ref: '#/definitions/response.Any'
+      security:
+      - SessionCookie: []
+      summary: 更新用户信息
+      tags:
+      - admin
  /api/v1/admin/users/{id}/status:
    put:
      consumes:
@@ -3843,7 +3977,7 @@ paths:
      - config
  /api/v1/custom/hello:
    get:
-      description: A sample business API for customization
+      description: Scaffold demo API; product APIs use semantic paths under apps/<domain>
      produces:
      - application/json
      responses: