Version: 0.9.82.dev.260507

后端： 1. 登录注册补齐极验行为验证与跨域入口：gateway 新增 `/user/captcha/register`，登录/注册先做 GeeTest 初始化与二次校验，再进入 user/auth RPC；补充验证码失败/初始化失败/服务不可用响应码，并新增可配置 CORS middleware 适配分域部署。 2. 容器部署配置入口收口：`bootstrap.LoadConfig` 支持 `SMARTFLOW_CONFIG_FILE` 与环境变量覆盖，`config.example.yaml` / `config.docker.yaml` 补齐 geetest 与容器内服务地址，网关新增配置列表解析，便于 compose 场景直接挂载配置启动。 3. LLM outbox 与助手时间线稳定性修正：`cmd/llm` 显式绑定 llm 自身 topic/group，避免误入 agent consumer group；agent timeline 在 Redis 热缓存未落 MySQL 时改用 `seq` 兜底临时 id，避免前端历史回放撞 key。前端： 4. 认证页接入极验并补齐提交前校验：新增 GeeTest 脚本加载与实例封装，登录/注册面板支持 challenge 初始化、切换面板重挂载、失败提示与提交前校验，认证 API/types 同步透传 geetest 三元组。 5. 前端部署基址与网关对接收口：Axios `baseURL`、Vue Router `history base` 与 Vite `base/dev proxy` 改为读取环境变量，新增 `frontend/.env.example`，支持子路径部署、容器内反向代理和本地联调共存。 6. 助手与工作台展示细节修正：AssistantPanel 历史重建优先使用真实 timeline id、缺失时退回 `seq` 保证消息主键唯一；首页主面板改为纵向可滚动并补底部留白，避免内容截断。仓库： 7. 整站容器化交付链路补齐并重写说明文档：新增后端/前端 Dockerfile、`.dockerignore`、前端 Nginx 代理、`docker-compose.full.yml`、`.env.full.example` 与镜像打包/导入脚本，README 改写数据库/路由/部署章节，并新增 `docs/容器化部署说明.md` 说明离线镜像分发方案。
2026-05-07 00:58:27 +08:00
parent 7b04b073ce
commit 25a608eaeb
35 changed files with 2412 additions and 327 deletions
--- a/backend/.dockerignore
+++ b/backend/.dockerignore
@@ -0,0 +1,5 @@
+.dev/
+.gocache/
+.gopath/
+bin/
+config.yaml
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1.7
+
+ARG GO_IMAGE=golang:1.25-bookworm
+ARG RUNTIME_IMAGE=debian:bookworm-slim
+
+FROM ${GO_IMAGE} AS builder
+
+WORKDIR /src/backend
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+ARG TARGETOS=linux
+ARG TARGETARCH=amd64
+
+# 1. 统一构建所有需要部署的后端服务二进制，避免每个服务维护一份 Dockerfile。
+# 2. 输出目录固定为 /out，便于运行时镜像按命令复用同一套产物。
+RUN --mount=type=cache,target=/root/.cache/go-build \
+    mkdir -p /out && \
+    for service in userauth notification active-scheduler schedule task task-class course memory agent taskclassforum tokenstore llm api; do \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o "/out/${service}" "./cmd/${service}"; \
+    done
+
+FROM ${RUNTIME_IMAGE} AS runtime
+
+WORKDIR /app/backend
+
+# 1. 运行时只保留证书与时区数据，保证 HTTPS 请求与国内时区配置可用。
+# 2. 默认附带一份容器配置模板，实际部署仍可通过挂载文件覆盖。
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /out /app/bin
+COPY config.docker.yaml /app/backend/config.docker.yaml
+
+ENV TZ=Asia/Shanghai
+ENV SMARTFLOW_CONFIG_FILE=/app/backend/config.docker.yaml
+
+CMD ["/app/bin/api"]
--- a/backend/cmd/llm/main.go
+++ b/backend/cmd/llm/main.go
@@ -116,8 +116,13 @@ func buildLLMOutboxDispatchEngine(outboxRepo *outboxinfra.Repository) (*outboxin
 		return nil, nil
 	}

+	// 1. LLM 进程这里只启动“LLM 自己 outbox 的 dispatch”，不应复用 kafka.LoadConfig() 里的全局默认 topic/group。
+	// 2. 全局默认值当前仍兼容指向 agent outbox；若只改 ServiceName 不同步改 Topic/GroupID，llm.exe 会误入 agent consumer group。
+	// 3. 因此这里显式绑定 llm 服务目录，确保 dispatch engine 只触达 llm_outbox_messages / smartflow.llm.outbox。
 	route, _ := outboxinfra.ResolveServiceRoute(outboxinfra.ServiceLLM)
-	kafkaCfg.ServiceName = outboxinfra.ServiceLLM
+	kafkaCfg.ServiceName = route.ServiceName
+	kafkaCfg.Topic = route.Topic
+	kafkaCfg.GroupID = route.GroupID
 	return outboxinfra.NewEngine(outboxRepo.WithRoute(route), kafkaCfg)
 }

--- a/backend/config.docker.yaml
+++ b/backend/config.docker.yaml
@@ -0,0 +1,259 @@
+# SmartFlow 容器化部署配置模板。
+#
+# 说明：
+# 1. 该文件面向 Docker Compose 内部网络，所有依赖地址都改为服务名。
+# 2. 本地开发仍可继续使用 backend/config.yaml，不与该文件冲突。
+# 3. 正式部署前请至少替换 JWT 密钥、模型密钥与外部服务凭证。
+
+server:
+  port: 8080
+
+database:
+  host: mysql
+  port: 3306
+  user: smartflow_user
+  password: "smartflow_password_456"
+  dbname: "smartflow"
+
+jwt:
+  accessSecret: "change_me_access_secret"
+  refreshSecret: "change_me_refresh_secret"
+  accessTokenExpire: 15min
+  refreshTokenExpire: 7d
+
+geetest:
+  captchaID: "80eb5b33de9fba62c69f5e57e36d9638"
+  privateKey: "991f9ad68191cbf6b823257ac67372f3"
+
+redis:
+  host: redis
+  port: 6379
+  password: "redis_password_789"
+
+userauth:
+  rpc:
+    listenOn: "0.0.0.0:9081"
+    endpoints:
+      - "userauth:9081"
+    timeout: 2s
+
+taskclassforum:
+  rpc:
+    listenOn: "0.0.0.0:9090"
+    endpoints:
+      - "taskclassforum:9090"
+    timeout: 2s
+
+tokenstore:
+  reward:
+    forumLikeAmount: 1
+    forumImportAmount: 5
+  rpc:
+    listenOn: "0.0.0.0:9095"
+    endpoints:
+      - "tokenstore:9095"
+    timeout: 2s
+
+llm:
+  rpc:
+    listenOn: "0.0.0.0:9096"
+    endpoints:
+      - "llm:9096"
+    timeout: 0s
+
+kafka:
+  enabled: true
+  brokers:
+    - "kafka:9092"
+  topic: "smartflow.agent.outbox"
+  groupID: "smartflow-agent-outbox-consumer"
+  retryScanInterval: 1s
+  retryBatchSize: 100
+  maxRetry: 20
+
+outbox:
+  services:
+    agent:
+      topic: "smartflow.agent.outbox"
+      groupID: "smartflow-agent-outbox-consumer"
+      table: "agent_outbox_messages"
+    task:
+      topic: "smartflow.task.outbox"
+      groupID: "smartflow-task-outbox-consumer"
+      table: "task_outbox_messages"
+    memory:
+      topic: "smartflow.memory.outbox"
+      groupID: "smartflow-memory-outbox-consumer"
+      table: "memory_outbox_messages"
+    active-scheduler:
+      topic: "smartflow.active-scheduler.outbox"
+      groupID: "smartflow-active-scheduler-outbox-consumer"
+      table: "active_scheduler_outbox_messages"
+    notification:
+      topic: "smartflow.notification.outbox"
+      groupID: "smartflow-notification-outbox-consumer"
+      table: "notification_outbox_messages"
+    taskclass-forum:
+      topic: "smartflow.taskclass-forum.outbox"
+      groupID: "smartflow-taskclass-forum-outbox-consumer"
+      table: "taskclass_forum_outbox_messages"
+    llm:
+      topic: "smartflow.llm.outbox"
+      groupID: "smartflow-llm-outbox-consumer"
+      table: "llm_outbox_messages"
+    token-store:
+      topic: "smartflow.token-store.outbox"
+      groupID: "smartflow-token-store-outbox-consumer"
+      table: "token_store_outbox_messages"
+
+notification:
+  rpc:
+    listenOn: "0.0.0.0:9082"
+    endpoints:
+      - "notification:9082"
+    timeout: 6s
+  frontendBaseURL: "https://smartflow.example.com"
+  retryScanEvery: 1m
+  retryBatchSize: 50
+
+cors:
+  allowedOrigins:
+    - "http://localhost:5173"
+    - "https://smartflow.example.com"
+
+schedule:
+  rpc:
+    listenOn: "0.0.0.0:9084"
+    endpoints:
+      - "schedule:9084"
+    timeout: 6s
+
+task:
+  rpc:
+    listenOn: "0.0.0.0:9085"
+    endpoints:
+      - "task:9085"
+    timeout: 6s
+
+taskClass:
+  rpc:
+    listenOn: "0.0.0.0:9086"
+    endpoints:
+      - "task-class:9086"
+    timeout: 6s
+
+course:
+  rpc:
+    listenOn: "0.0.0.0:9087"
+    endpoints:
+      - "course:9087"
+    timeout: 5m
+
+activeScheduler:
+  rpc:
+    listenOn: "0.0.0.0:9083"
+    endpoints:
+      - "active-scheduler:9083"
+    timeout: 8s
+  jobScanEvery: 1m
+  jobScanLimit: 50
+
+time:
+  zone: "Asia/Shanghai"
+  semesterStartDate: "2026-03-02"
+  semesterEndDate: "2026-07-19"
+
+agent:
+  rpc:
+    listenOn: "0.0.0.0:9089"
+    endpoints:
+      - "agent:9089"
+    timeout: 0s
+    chat:
+      enabled: true
+    api:
+      enabled: true
+  liteModel: "doubao-seed-2-0-code-preview-260215"
+  proModel: "doubao-seed-2-0-code-preview-260215"
+  maxModel: "doubao-seed-2-0-code-preview-260215"
+  baseURL: "https://ark.cn-beijing.volces.com/api/v3"
+  thinking:
+    plan: true
+    execute: true
+    deliver: false
+    memory: false
+
+courseImport:
+  visionModel: ""
+  maxImageBytes: 5242880
+  maxTokens: 8192
+
+rag:
+  enabled: true
+  store: "milvus"
+  topK: 8
+  threshold: 0.55
+  retrieve:
+    timeoutMs: 1500
+  ingest:
+    chunkSize: 400
+    chunkOverlap: 80
+  embed:
+    provider: "eino"
+    model: "doubao-embedding-vision-251215"
+    baseURL: "https://ark.cn-beijing.volces.com/api/v3"
+    timeoutMs: 1200
+    dimension: 1024
+  reranker:
+    enabled: false
+    provider: "noop"
+    timeoutMs: 1200
+  milvus:
+    address: "http://milvus-standalone:19530"
+    token: "root:Milvus"
+    dbName: ""
+    collectionName: "smartflow_rag_chunks"
+    metricType: "COSINE"
+    requestTimeoutMs: 1500
+
+memory:
+  rpc:
+    listenOn: "0.0.0.0:9088"
+    endpoints:
+      - "memory:9088"
+    timeout: 6s
+  enabled: true
+  rag:
+    enabled: true
+  read:
+    mode: legacy
+    constraintLimit: 5
+    preferenceLimit: 5
+    factLimit: 5
+  inject:
+    renderMode: flat
+  prompt:
+    extract: ""
+    decision: ""
+  threshold: 0.55
+  enableReranker: false
+  llm:
+    temperature: 0.1
+    topP: 0.2
+  job:
+    maxRetry: 6
+  worker:
+    pollEvery: 2s
+    claimBatch: 1
+  decision:
+    enabled: true
+    candidateTopK: 5
+    candidateMinScore: 0.6
+    fallbackMode: legacy_add
+  write:
+    mode: legacy
+    minConfidence: 0.5
+
+websearch:
+  provider: bocha
+  apiKey: ""
--- a/backend/config.example.yaml
+++ b/backend/config.example.yaml
@@ -23,6 +23,11 @@ jwt:
  accessTokenExpire: 15min
  refreshTokenExpire: 7d

+# 极验行为验证配置。
+geetest:
+  captchaID: "put_your_geetest_captcha_id_here"
+  privateKey: "put_your_geetest_private_key_here"
+
 # Redis 配置。
 redis:
  host: localhost
--- a/backend/gateway/api/userauth/dto.go
+++ b/backend/gateway/api/userauth/dto.go
@@ -0,0 +1,59 @@
+package userauthapi
+
+import contracts "github.com/LoveLosita/smartflow/backend/shared/contracts/userauth"
+
+// geeTestValidatePayload 只承载 gateway 边界的人机验证字段。
+// 职责边界：
+// 1. 负责承接前端提交的 geetest 三元组；
+// 2. 不负责 user/auth RPC 入参映射，避免把第三方验证码字段带入内部服务契约；
+// 3. 不负责校验逻辑，真正校验由 GeeTestService 完成。
+type geeTestValidatePayload struct {
+	Challenge string `json:"geetest_challenge"`
+	Validate  string `json:"geetest_validate"`
+	Seccode   string `json:"geetest_seccode"`
+}
+
+type registerRequest struct {
+	Username    string `json:"username"`
+	Password    string `json:"password"`
+	PhoneNumber string `json:"phone_number"`
+
+	geeTestValidatePayload
+}
+
+func (r registerRequest) toContract() contracts.RegisterRequest {
+	return contracts.RegisterRequest{
+		Username:    r.Username,
+		Password:    r.Password,
+		PhoneNumber: r.PhoneNumber,
+	}
+}
+
+func (r registerRequest) captchaPayload() geeTestValidatePayload {
+	return r.geeTestValidatePayload
+}
+
+type loginRequest struct {
+	Username string `json:"username"`
+	Password string `json:"password"`
+
+	geeTestValidatePayload
+}
+
+func (r loginRequest) toContract() contracts.LoginRequest {
+	return contracts.LoginRequest{
+		Username: r.Username,
+		Password: r.Password,
+	}
+}
+
+func (r loginRequest) captchaPayload() geeTestValidatePayload {
+	return r.geeTestValidatePayload
+}
+
+type captchaRegisterResponse struct {
+	Success    int    `json:"success"`
+	GT         string `json:"gt"`
+	Challenge  string `json:"challenge"`
+	NewCaptcha bool   `json:"new_captcha"`
+}
--- a/backend/gateway/api/userauth/geetest.go
+++ b/backend/gateway/api/userauth/geetest.go
@@ -0,0 +1,188 @@
+package userauthapi
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/gateway/shared/respond"
+	"github.com/spf13/viper"
+)
+
+const (
+	geeTestRegisterURL = "https://api.geetest.com/register.php"
+	geeTestValidateURL = "http://api.geetest.com/validate.php"
+	geeTestClientType  = "web"
+	geeTestSDKName     = "smartflow-gateway-go/1.0"
+)
+
+type geeTestRegisterUpstreamResponse struct {
+	Challenge string `json:"challenge"`
+}
+
+type geeTestValidateUpstreamResponse struct {
+	Seccode string `json:"seccode"`
+}
+
+// GeeTestService 负责封装 gateway 与极验 v3 接口的最小交互。
+// 职责边界：
+// 1. 只处理验证码初始化与二次校验，不承载登录/注册业务；
+// 2. 只暴露 gateway HTTP 层真正需要的最小方法，避免把第三方协议散落到 handler；
+// 3. 不做离线 failback 存储，当前阶段聚焦“在线校验闭环”这一个能力域。
+type GeeTestService struct {
+	captchaID  string
+	privateKey string
+	httpClient *http.Client
+}
+
+func NewGeeTestServiceFromConfig() *GeeTestService {
+	return &GeeTestService{
+		captchaID:  strings.TrimSpace(viper.GetString("geetest.captchaID")),
+		privateKey: strings.TrimSpace(viper.GetString("geetest.privateKey")),
+		httpClient: &http.Client{Timeout: 3 * time.Second},
+	}
+}
+
+// Register 负责向极验申请当前页 challenge，并转成前端 `initGeetest` 可直接消费的结构。
+// 职责边界：
+// 1. 只对应官方 API1 初始化；
+// 2. 不负责缓存 challenge，也不负责表单业务字段；
+// 3. 若极验服务不可用，直接返回初始化失败，让前端走显式提示。
+func (s *GeeTestService) Register(ctx context.Context, clientIP string) (*captchaRegisterResponse, error) {
+	if !s.isConfigured() {
+		return nil, respond.CaptchaInitFailed
+	}
+
+	// 1. 先按官方 API1 约定拉取原始 challenge。
+	// 2. 再使用 privateKey 做一次签名混淆，避免把上游原始 challenge 直接暴露给前端。
+	// 3. 任一步失败都直接中断，让登录/注册入口显式暴露初始化异常。
+	query := url.Values{}
+	query.Set("digestmod", "md5")
+	query.Set("gt", s.captchaID)
+	query.Set("json_format", "1")
+	query.Set("sdk", geeTestSDKName)
+	query.Set("client_type", geeTestClientType)
+	if ip := strings.TrimSpace(clientIP); ip != "" {
+		query.Set("ip_address", ip)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, geeTestRegisterURL+"?"+query.Encode(), nil)
+	if err != nil {
+		return nil, respond.CaptchaInitFailed
+	}
+
+	resp, err := s.httpClient.Do(req)
+	if err != nil {
+		return nil, respond.CaptchaInitFailed
+	}
+	defer resp.Body.Close()
+
+	rawBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, respond.CaptchaInitFailed
+	}
+
+	challenge := extractRegisterChallenge(rawBody)
+	if challenge == "" {
+		return nil, respond.CaptchaInitFailed
+	}
+
+	return &captchaRegisterResponse{
+		Success:    1,
+		GT:         s.captchaID,
+		Challenge:  md5Hex(challenge + s.privateKey),
+		NewCaptcha: true,
+	}, nil
+}
+
+// Verify 负责校验前端回传的极验三元组。
+// 职责边界：
+// 1. 先做本地 challenge/validate 一致性检查，尽早拦截无效请求；
+// 2. 再调用官方 API2 校验 seccode，保证验证码结果真实有效；
+// 3. 只返回“通过/失败/服务不可用”三类结论，不混入登录注册业务判断。
+func (s *GeeTestService) Verify(ctx context.Context, payload geeTestValidatePayload, clientIP string) error {
+	if !s.isConfigured() {
+		return respond.CaptchaVerifyUnavailable
+	}
+
+	challenge := strings.TrimSpace(payload.Challenge)
+	validate := strings.TrimSpace(payload.Validate)
+	seccode := strings.TrimSpace(payload.Seccode)
+	if challenge == "" || validate == "" || seccode == "" {
+		return respond.MissingParam
+	}
+
+	// 1. 先按极验 v3 协议校验 validate 是否与 challenge/privateKey 匹配。
+	// 2. 若本地签名都对不上，直接判失败，避免继续请求第三方接口。
+	// 3. 只有本地签名通过后，才继续调用 API2 复核 seccode。
+	expectedValidate := md5Hex(s.privateKey + "geetest" + challenge)
+	if !strings.EqualFold(validate, expectedValidate) {
+		return respond.CaptchaVerifyFailed
+	}
+
+	form := url.Values{}
+	form.Set("captchaid", s.captchaID)
+	form.Set("challenge", challenge)
+	form.Set("seccode", seccode)
+	form.Set("json_format", "1")
+	form.Set("sdk", geeTestSDKName)
+	form.Set("client_type", geeTestClientType)
+	if ip := strings.TrimSpace(clientIP); ip != "" {
+		form.Set("ip_address", ip)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, geeTestValidateURL, strings.NewReader(form.Encode()))
+	if err != nil {
+		return respond.CaptchaVerifyUnavailable
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := s.httpClient.Do(req)
+	if err != nil {
+		return respond.CaptchaVerifyUnavailable
+	}
+	defer resp.Body.Close()
+
+	rawBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return respond.CaptchaVerifyUnavailable
+	}
+
+	if !matchValidateSeccode(rawBody, seccode) {
+		return respond.CaptchaVerifyFailed
+	}
+	return nil
+}
+
+func (s *GeeTestService) isConfigured() bool {
+	return s != nil && s.captchaID != "" && s.privateKey != ""
+}
+
+func extractRegisterChallenge(rawBody []byte) string {
+	var payload geeTestRegisterUpstreamResponse
+	if err := json.Unmarshal(rawBody, &payload); err == nil {
+		return strings.TrimSpace(payload.Challenge)
+	}
+	return strings.TrimSpace(string(rawBody))
+}
+
+func matchValidateSeccode(rawBody []byte, seccode string) bool {
+	expected := md5Hex(strings.TrimSpace(seccode))
+
+	var payload geeTestValidateUpstreamResponse
+	if err := json.Unmarshal(rawBody, &payload); err == nil {
+		return strings.EqualFold(strings.TrimSpace(payload.Seccode), expected)
+	}
+	return strings.EqualFold(strings.TrimSpace(string(rawBody)), expected)
+}
+
+func md5Hex(input string) string {
+	sum := md5.Sum([]byte(input))
+	return hex.EncodeToString(sum[:])
+}
--- a/backend/gateway/api/userauth/handler.go
+++ b/backend/gateway/api/userauth/handler.go
@@ -14,25 +14,51 @@ import (
 )

 type UserHandler struct {
-	client ports.UserCommandClient
+	client  ports.UserCommandClient
+	captcha *GeeTestService
 }

-// NewUserHandler 只接收 user/auth 客户端，不再直接依赖本地 user service。
-func NewUserHandler(client ports.UserCommandClient) *UserHandler {
-	return &UserHandler{client: client}
+// NewUserHandler 只接收 user/auth 客户端与验证码服务，不再直接依赖本地 user service。
+func NewUserHandler(client ports.UserCommandClient, captcha *GeeTestService) *UserHandler {
+	return &UserHandler{
+		client:  client,
+		captcha: captcha,
+	}
+}
+
+func (api *UserHandler) CaptchaRegister(c *gin.Context) {
+	captchaCtx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
+	defer cancel()
+
+	registerData, err := api.captcha.Register(captchaCtx, c.ClientIP())
+	if err != nil {
+		respond.DealWithError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, respond.RespWithData(respond.Ok, registerData))
 }

 func (api *UserHandler) UserRegister(c *gin.Context) {
-	var req contracts.RegisterRequest
+	var req registerRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}

+	// 1. 先用独立超时完成极验二次校验，避免第三方接口抖动侵入内部 RPC 超时预算。
+	// 2. 只有验证码通过后才继续调 user/auth 注册服务，防止无效流量进入内部链路。
+	// 3. 内部 RPC 仍保留原先 2 秒超时边界，不改变现有 user/auth 服务 SLA。
+	captchaCtx, cancelCaptcha := context.WithTimeout(c.Request.Context(), 3*time.Second)
+	defer cancelCaptcha()
+	if err := api.captcha.Verify(captchaCtx, req.captchaPayload(), c.ClientIP()); err != nil {
+		respond.DealWithError(c, err)
+		return
+	}
+
 	ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
 	defer cancel()

-	retUser, err := api.client.Register(ctx, req)
+	retUser, err := api.client.Register(ctx, req.toContract())
 	if err != nil {
 		respond.DealWithError(c, err)
 		return
@@ -41,16 +67,23 @@ func (api *UserHandler) UserRegister(c *gin.Context) {
 }

 func (api *UserHandler) UserLogin(c *gin.Context) {
-	var req contracts.LoginRequest
+	var req loginRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, respond.WrongParamType)
 		return
 	}

+	captchaCtx, cancelCaptcha := context.WithTimeout(c.Request.Context(), 3*time.Second)
+	defer cancelCaptcha()
+	if err := api.captcha.Verify(captchaCtx, req.captchaPayload(), c.ClientIP()); err != nil {
+		respond.DealWithError(c, err)
+		return
+	}
+
 	ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
 	defer cancel()

-	tokens, err := api.client.Login(ctx, req)
+	tokens, err := api.client.Login(ctx, req.toContract())
 	if err != nil {
 		respond.DealWithError(c, err)
 		return
--- a/backend/gateway/api/userauth/routes.go
+++ b/backend/gateway/api/userauth/routes.go
@@ -20,6 +20,7 @@ func RegisterRoutes(apiGroup *gin.RouterGroup, handler *UserHandler, authClient

 	userGroup := apiGroup.Group("/user")
 	{
+		userGroup.GET("/captcha/register", handler.CaptchaRegister)
 		userGroup.POST("/register", handler.UserRegister)
 		userGroup.POST("/login", handler.UserLogin)
 		userGroup.POST("/refresh-token", handler.RefreshTokenHandler)
--- a/backend/gateway/middleware/cors.go
+++ b/backend/gateway/middleware/cors.go
@@ -0,0 +1,147 @@
+package middleware
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+type CORSOptions struct {
+	AllowedOrigins   []string
+	AllowedMethods   []string
+	AllowedHeaders   []string
+	ExposedHeaders   []string
+	AllowCredentials bool
+	MaxAge           time.Duration
+}
+
+func CORSMiddleware(opts CORSOptions) gin.HandlerFunc {
+	origins := normalizeHeaderValues(opts.AllowedOrigins)
+	if len(origins) == 0 {
+		return func(c *gin.Context) {
+			c.Next()
+		}
+	}
+
+	methods := normalizeHeaderValuesWithDefaults(opts.AllowedMethods, []string{
+		http.MethodGet,
+		http.MethodPost,
+		http.MethodPut,
+		http.MethodPatch,
+		http.MethodDelete,
+		http.MethodOptions,
+	})
+	headers := normalizeHeaderValuesWithDefaults(opts.AllowedHeaders, []string{
+		"Authorization",
+		"Content-Type",
+		"Accept",
+		"Origin",
+		"X-Requested-With",
+		"Idempotency-Key",
+	})
+	exposedHeaders := normalizeHeaderValues(opts.ExposedHeaders)
+	maxAge := opts.MaxAge
+	if maxAge <= 0 {
+		maxAge = 12 * time.Hour
+	}
+
+	return func(c *gin.Context) {
+		origin := strings.TrimSpace(c.GetHeader("Origin"))
+		if origin == "" {
+			c.Next()
+			return
+		}
+
+		allowedOrigin := matchAllowedOrigin(origin, origins)
+		if allowedOrigin == "" {
+			if c.Request.Method == http.MethodOptions {
+				c.AbortWithStatus(http.StatusForbidden)
+				return
+			}
+			c.Next()
+			return
+		}
+
+		setVaryHeader(c.Writer.Header(), "Origin")
+		c.Header("Access-Control-Allow-Origin", allowedOrigin)
+		if opts.AllowCredentials && allowedOrigin != "*" {
+			c.Header("Access-Control-Allow-Credentials", "true")
+		}
+		if len(exposedHeaders) > 0 {
+			c.Header("Access-Control-Expose-Headers", strings.Join(exposedHeaders, ", "))
+		}
+
+		if c.Request.Method == http.MethodOptions {
+			setVaryHeader(c.Writer.Header(), "Access-Control-Request-Method")
+			setVaryHeader(c.Writer.Header(), "Access-Control-Request-Headers")
+			c.Header("Access-Control-Allow-Methods", strings.Join(methods, ", "))
+			c.Header("Access-Control-Allow-Headers", strings.Join(headers, ", "))
+			c.Header("Access-Control-Max-Age", formatMaxAgeSeconds(maxAge))
+			c.AbortWithStatus(http.StatusNoContent)
+			return
+		}
+
+		c.Next()
+	}
+}
+
+func matchAllowedOrigin(origin string, allowedOrigins []string) string {
+	for _, allowedOrigin := range allowedOrigins {
+		if allowedOrigin == "*" {
+			return "*"
+		}
+		if strings.EqualFold(origin, allowedOrigin) {
+			return origin
+		}
+	}
+	return ""
+}
+
+func normalizeHeaderValues(values []string) []string {
+	seen := make(map[string]struct{}, len(values))
+	normalized := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed == "" {
+			continue
+		}
+		key := strings.ToLower(trimmed)
+		if _, exists := seen[key]; exists {
+			continue
+		}
+		seen[key] = struct{}{}
+		normalized = append(normalized, trimmed)
+	}
+	return normalized
+}
+
+func normalizeHeaderValuesWithDefaults(values []string, defaults []string) []string {
+	normalized := normalizeHeaderValues(values)
+	if len(normalized) > 0 {
+		return normalized
+	}
+	return normalizeHeaderValues(defaults)
+}
+
+func setVaryHeader(header http.Header, value string) {
+	existing := header.Values("Vary")
+	for _, entry := range existing {
+		for _, part := range strings.Split(entry, ",") {
+			if strings.EqualFold(strings.TrimSpace(part), value) {
+				return
+			}
+		}
+	}
+	header.Add("Vary", value)
+}
+
+func formatMaxAgeSeconds(maxAge time.Duration) string {
+	seconds := int(maxAge / time.Second)
+	if seconds < 0 {
+		seconds = 0
+	}
+	return strconv.Itoa(seconds)
+}
--- a/backend/gateway/router/router.go
+++ b/backend/gateway/router/router.go
@@ -5,6 +5,7 @@ import (
 	"errors"
 	"log"
 	"net/http"
+	"strings"
 	"time"

 	taskclassforumclient "github.com/LoveLosita/smartflow/backend/client/taskclassforum"
@@ -68,6 +69,13 @@ func RegisterRouters(
 	limiter *ratelimit.RateLimiter,
 ) *gin.Engine {
 	r := gin.Default()
+	r.Use(gatewaymiddleware.CORSMiddleware(gatewaymiddleware.CORSOptions{
+		AllowedOrigins:   readConfigList("cors.allowedOrigins"),
+		AllowedMethods:   readConfigList("cors.allowedMethods"),
+		AllowedHeaders:   readConfigList("cors.allowedHeaders"),
+		ExposedHeaders:   readConfigList("cors.exposedHeaders"),
+		AllowCredentials: viper.GetBool("cors.allowCredentials"),
+	}))
 	apiGroup := r.Group("/api/v1")
 	{
 		apiGroup.GET("/health", func(c *gin.Context) {
@@ -77,7 +85,7 @@ func RegisterRouters(
 			})
 		})

-		userauthapi.RegisterRoutes(apiGroup, userauthapi.NewUserHandler(authClient), authClient, limiter)
+		userauthapi.RegisterRoutes(apiGroup, userauthapi.NewUserHandler(authClient, userauthapi.NewGeeTestServiceFromConfig()), authClient, limiter)
 		forumapi.RegisterRoutes(apiGroup, forumapi.NewHandler(forumClient), authClient, cache, limiter)
 		tokenstoreapi.RegisterRoutes(apiGroup, tokenstoreapi.NewHandler(tokenStoreClient), authClient, cache, limiter)

@@ -173,3 +181,53 @@ func RegisterRouters(
 	log.Println("Routes setup completed")
 	return r
 }
+
+func readConfigList(key string) []string {
+	values := viper.GetStringSlice(key)
+	if len(values) > 0 {
+		return compactConfigList(expandConfigList(values))
+	}
+
+	raw := strings.TrimSpace(viper.GetString(key))
+	if raw == "" {
+		return nil
+	}
+
+	splitted := strings.FieldsFunc(raw, func(r rune) bool {
+		return r == ',' || r == '\n' || r == '\r' || r == ';'
+	})
+	return compactConfigList(splitted)
+}
+
+func expandConfigList(values []string) []string {
+	expanded := make([]string, 0, len(values))
+	for _, value := range values {
+		parts := strings.FieldsFunc(value, func(r rune) bool {
+			return r == ',' || r == '\n' || r == '\r' || r == ';'
+		})
+		if len(parts) == 0 {
+			expanded = append(expanded, value)
+			continue
+		}
+		expanded = append(expanded, parts...)
+	}
+	return expanded
+}
+
+func compactConfigList(values []string) []string {
+	seen := make(map[string]struct{}, len(values))
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed == "" {
+			continue
+		}
+		key := strings.ToLower(trimmed)
+		if _, exists := seen[key]; exists {
+			continue
+		}
+		seen[key] = struct{}{}
+		result = append(result, trimmed)
+	}
+	return result
+}
--- a/backend/gateway/shared/respond/respond.go
+++ b/backend/gateway/shared/respond/respond.go
@@ -39,6 +39,9 @@ var (
 	TokenUsageExceedsLimit      = rootrespond.TokenUsageExceedsLimit
 	ConversationNotFound        = rootrespond.ConversationNotFound
 	MissingConversationID       = rootrespond.MissingConversationID
+	CaptchaVerifyFailed         = rootrespond.CaptchaVerifyFailed
+	CaptchaInitFailed           = rootrespond.CaptchaInitFailed
+	CaptchaVerifyUnavailable    = rootrespond.CaptchaVerifyUnavailable
 )

 // RespWithData 为 gateway HTTP 门面生成带 data 的统一响应体。
--- a/backend/services/agent/sv/agent_timeline.go
+++ b/backend/services/agent/sv/agent_timeline.go
@@ -382,6 +382,14 @@ func buildConversationTimelineCacheItem(
 	tokensConsumed int,
 	createdAt *time.Time,
 ) model.GetConversationTimelineItem {
+	// 1. Redis 热缓存先于 MySQL 落库写入时，eventID 可能暂时为 0。
+	// 2. 如果把 0 原样透传给前端，历史重建阶段所有 cache-only 事件都会共享同一个“空 id”。
+	// 3. 前端常把 timeline id 当消息/块的挂载主键，撞 key 后会把不同轮次的 assistant 状态桶错误复用。
+	// 4. 因此这里在未拿到真实主键时，先退回使用会话内唯一的 seq 作为临时 id；待后续从 DB 回源时再自然切换为真实 id。
+	if eventID <= 0 && seq > 0 {
+		eventID = seq
+	}
+
 	item := model.GetConversationTimelineItem{
 		ID:             eventID,
 		Seq:            seq,
--- a/backend/shared/infra/bootstrap/config.go
+++ b/backend/shared/infra/bootstrap/config.go
@@ -3,17 +3,29 @@ package bootstrap
 import (
 	"fmt"
 	"log"
+	"os"
+	"strings"

 	"github.com/spf13/viper"
 )

-// LoadConfig 统一加载后端进程配置。
-//
-// 职责边界：
-// 1. 只负责把 config.yaml 读入 viper，不解释具体业务配置语义。
-// 2. 同时兼容从仓库根目录和 backend 目录启动的两种路径。
-// 3. 失败时返回 error，由各进程入口决定是否退出。
+const configFileEnv = "SMARTFLOW_CONFIG_FILE"
+
 func LoadConfig() error {
+	viper.Reset()
+	viper.SetEnvPrefix("SMARTFLOW")
+	viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+	viper.AutomaticEnv()
+
+	if configFile := os.Getenv(configFileEnv); configFile != "" {
+		viper.SetConfigFile(configFile)
+		if err := viper.ReadInConfig(); err != nil {
+			return fmt.Errorf("failed to read config file %q: %w", configFile, err)
+		}
+		log.Printf("Config loaded successfully from %s", configFile)
+		return nil
+	}
+
 	viper.SetConfigName("config")
 	viper.SetConfigType("yaml")
 	viper.AddConfigPath(".")
--- a/backend/shared/respond/respond.go
+++ b/backend/shared/respond/respond.go
@@ -391,6 +391,11 @@ var ( //请求相关的响应
 		Info:   "no fields to update",
 	}

+	CaptchaVerifyFailed = Response{ //人机验证未通过
+		Status: "40064",
+		Info:   "人机验证未通过",
+	}
+
 	TaskAlreadyDeleted = Response{ //任务已删除或不存在（幂等信息码）
 		Status: "10003",
 		Info:   "task already deleted or not found",
@@ -405,4 +410,14 @@ var ( //请求相关的响应
 		Status: "50002",
 		Info:   "schedule refine output parse failed",
 	}
+
+	CaptchaInitFailed = Response{ //人机验证初始化失败
+		Status: "50003",
+		Info:   "人机验证初始化失败",
+	}
+
+	CaptchaVerifyUnavailable = Response{ //人机验证服务暂不可用
+		Status: "50004",
+		Info:   "人机验证服务暂不可用",
+	}
 )