Version: 0.4.9.dev.260309
feat: 🗄️ 新增自动建表功能 * 新增项目启动时自动建表能力，减少手动初始化数据库步骤 * 解决 `agent_chat` 与 `chat_history` 结构体互相持有对方结构体用于 `preload` 导致的循环依赖问题 * 修复因结构体互相依赖引发的建表失败问题，保证数据库初始化流程稳定 feat: 🐳 Docker Compose 引入 Kafka 分区自动初始化 * 更新 `docker-compose` 配置，引入 Kafka partition 自动初始化脚本 * 保证服务启动后 Topic 即具备可用 partition，实现开箱即用 * 修复转移环境后 MySQL 等容器数据无法持久化的问题，统一改为使用命名卷进行数据持久化 docs: 📚 补充 Outbox + Kafka 持久化链路注释 * 为 Outbox + Kafka 消息持久化链路补充详细代码注释 * 提升异步消息链路的可读性与维护性 * 当前代码 Review 进度约 50% undo: ⚠️ Kafka 初始化阶段出现消息短暂堆积 * 初次初始化项目时观察到消息在 Kafka 中短暂堆积现象 * 后续被消费者一次性消费且未再次复现 * 已在生产者启动、消费者启动以及消息消费流程中增加控制台日志输出，降低系统黑箱程度 * 后续若条件允许将进一步排查该现象的触发原因
This commit is contained in:
Losita
@@ -3,17 +3,17 @@ package model
|
||||
import "time"
|
||||
|
||||
type UserSendMessageRequest struct {
|
||||
ConversationID string `json:"conversation_id,omitempty"` // 可选，指定对话 ID
|
||||
ConversationID string `json:"conversation_id,omitempty"`
|
||||
Message string `json:"message" binding:"required"`
|
||||
Model string `json:"model,omitempty"` // 可选，指定使用的模型
|
||||
Thinking bool `json:"thinking,omitempty"` // 可选，是否开启思考模式
|
||||
Model string `json:"model,omitempty"`
|
||||
Thinking bool `json:"thinking,omitempty"`
|
||||
}
|
||||
|
||||
type SSEResponse struct {
|
||||
Event string `json:"event"` // 事件类型，如 "message"、"error" 等
|
||||
ID int `json:"id,omitempty"` // SSE 的 id 字段
|
||||
Retry int64 `json:"retry,omitempty"` // SSE 的 retry 字段（毫秒）
|
||||
Data SSEMessageData `json:"data"` // 事件数据
|
||||
Event string `json:"event"`
|
||||
ID int `json:"id,omitempty"`
|
||||
Retry int64 `json:"retry,omitempty"`
|
||||
Data SSEMessageData `json:"data"`
|
||||
}
|
||||
|
||||
type SSEMessageData struct {
|
||||
@@ -23,35 +23,33 @@ type SSEMessageData struct {
|
||||
|
||||
type AgentChat struct {
|
||||
ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:自增ID"`
|
||||
ChatID string `gorm:"column:chat_id;type:varchar(36);not null;uniqueIndex:uk_chat_id;comment:会话ID，UUID格式"`
|
||||
UserID int `gorm:"column:user_id;not null;index:idx_user_last,priority:1;index:idx_user_status,priority:1;comment:所属用户"`
|
||||
ChatID string `gorm:"column:chat_id;type:varchar(36);not null;uniqueIndex:uk_chat_id;comment:会话UUID"`
|
||||
UserID int `gorm:"column:user_id;not null;index:idx_user_last,priority:1;index:idx_user_status,priority:1;comment:所属用户ID"`
|
||||
Title *string `gorm:"column:title;type:varchar(255);comment:会话标题"`
|
||||
SystemPrompt *string `gorm:"column:system_prompt;type:text;comment:可选：系统提示词/会话级上下文"`
|
||||
Model *string `gorm:"column:model;type:varchar(100);comment:可选：使用的模型标识"`
|
||||
MessageCount int `gorm:"column:message_count;not null;default:0;comment:消息数（可冗余）"`
|
||||
TokensTotal int `gorm:"column:tokens_total;not null;default:0;comment:累计消耗（可冗余）"`
|
||||
LastMessageAt *time.Time `gorm:"column:last_message_at;comment:最后一条消息时间"`
|
||||
Status string `gorm:"column:status;type:varchar(32);not null;default:active;index:idx_user_status,priority:2;comment:active/archived"`
|
||||
SystemPrompt *string `gorm:"column:system_prompt;type:text;comment:系统提示词"`
|
||||
Model *string `gorm:"column:model;type:varchar(100);comment:模型标识"`
|
||||
MessageCount int `gorm:"column:message_count;not null;default:0;comment:消息总数"`
|
||||
TokensTotal int `gorm:"column:tokens_total;not null;default:0;comment:累计Token"`
|
||||
LastMessageAt *time.Time `gorm:"column:last_message_at;comment:最后消息时间"`
|
||||
Status string `gorm:"column:status;type:varchar(32);not null;default:active;index:idx_user_status,priority:2;comment:会话状态"`
|
||||
CreatedAt *time.Time `gorm:"column:created_at;autoCreateTime"`
|
||||
UpdatedAt *time.Time `gorm:"column:updated_at;autoUpdateTime"`
|
||||
DeletedAt *time.Time `gorm:"column:deleted_at;comment:软删除"`
|
||||
// 关联：一个会话有多条消息
|
||||
Chats []ChatHistory `gorm:"foreignKey:ChatID;references:ChatID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
|
||||
DeletedAt *time.Time `gorm:"column:deleted_at;comment:软删除时间"`
|
||||
}
|
||||
|
||||
func (AgentChat) TableName() string { return "agent_chats" }
|
||||
|
||||
type ChatHistory struct {
|
||||
ID int `gorm:"column:id;primaryKey;autoIncrement"`
|
||||
ChatID string `gorm:"column:chat_id;type:varchar(36);not null;index:idx_user_chat,priority:2;index:idx_chat_id;comment:对话UUID"`
|
||||
ChatID string `gorm:"column:chat_id;type:varchar(36);not null;index:idx_user_chat,priority:2;index:idx_chat_id;comment:会话UUID"`
|
||||
UserID int `gorm:"column:user_id;not null;index:idx_user_chat,priority:1"`
|
||||
MessageContent *string `gorm:"column:message_content;type:text;comment:用户或AI的话"`
|
||||
Role *string `gorm:"column:role;type:varchar(32);comment:user / assistant"`
|
||||
TokensConsumed int `gorm:"column:tokens_consumed;not null;default:0;comment:单次消耗，用于累加到 users 表"`
|
||||
MessageContent *string `gorm:"column:message_content;type:text;comment:消息内容"`
|
||||
Role *string `gorm:"column:role;type:varchar(32);comment:消息角色"`
|
||||
TokensConsumed int `gorm:"column:tokens_consumed;not null;default:0;comment:本轮消耗Token"`
|
||||
CreatedAt *time.Time `gorm:"column:created_at;autoCreateTime"`
|
||||
|
||||
// 可选：回挂会话（按 chat_id -> chat_histories.chat_id）
|
||||
ChatHistory AgentChat `gorm:"foreignKey:ChatID;references:ChatID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
|
||||
// 只保留从聊天记录到会话的单向关联，避免迁移时出现循环依赖。
|
||||
Chat AgentChat `gorm:"foreignKey:ChatID;references:ChatID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
|
||||
}
|
||||
|
||||
func (ChatHistory) TableName() string { return "chat_histories" }
|
||||
|
||||
@@ -3,26 +3,40 @@ package model
|
||||
import "time"
|
||||
|
||||
const (
|
||||
OutboxStatusPending = "pending"
|
||||
// OutboxStatusPending 表示消息已落 outbox，等待投递或等待下次重试窗口到达。
|
||||
OutboxStatusPending = "pending"
|
||||
// OutboxStatusPublished 表示消息已成功写入 Kafka，但尚未完成业务消费。
|
||||
OutboxStatusPublished = "published"
|
||||
OutboxStatusConsumed = "consumed"
|
||||
OutboxStatusDead = "dead"
|
||||
// OutboxStatusConsumed 表示消息对应的业务逻辑已成功执行（本项目中即聊天记录已落库）。
|
||||
OutboxStatusConsumed = "consumed"
|
||||
// OutboxStatusDead 表示达到最大重试次数或出现不可恢复错误，进入死信终态。
|
||||
OutboxStatusDead = "dead"
|
||||
|
||||
// OutboxBizTypeChatHistoryPersist 当前唯一业务类型：聊天记录异步持久化。
|
||||
OutboxBizTypeChatHistoryPersist = "chat_history_persist"
|
||||
)
|
||||
|
||||
// AgentOutboxMessage 保存需要异步投递到 Kafka 的消息。
|
||||
// AgentOutboxMessage 是 outbox 模式的核心表结构：
|
||||
// 1. 先写本地数据库（保证事务内可见）；
|
||||
// 2. 再由后台扫描并投递 Kafka；
|
||||
// 3. 由消费者完成最终业务落库并回写状态。
|
||||
type AgentOutboxMessage struct {
|
||||
ID int64 `gorm:"column:id;primaryKey;autoIncrement"`
|
||||
BizType string `gorm:"column:biz_type;type:varchar(64);not null;index:idx_outbox_status_next,priority:3;comment:业务类型"`
|
||||
Topic string `gorm:"column:topic;type:varchar(128);not null;comment:Kafka Topic"`
|
||||
MessageKey string `gorm:"column:message_key;type:varchar(128);not null;comment:Kafka 消息键"`
|
||||
Payload string `gorm:"column:payload;type:longtext;not null;comment:业务载荷(JSON)"`
|
||||
ID int64 `gorm:"column:id;primaryKey;autoIncrement"`
|
||||
// BizType 决定消费者侧如何解释 Payload。
|
||||
BizType string `gorm:"column:biz_type;type:varchar(64);not null;index:idx_outbox_status_next,priority:3;comment:业务类型"`
|
||||
// Topic/MessageKey 用于 Kafka 路由与分区稳定性。
|
||||
Topic string `gorm:"column:topic;type:varchar(128);not null;comment:Kafka Topic"`
|
||||
MessageKey string `gorm:"column:message_key;type:varchar(128);not null;comment:Kafka 消息键"`
|
||||
// Payload 存储业务 JSON，消费时再反序列化为具体 payload 结构。
|
||||
Payload string `gorm:"column:payload;type:longtext;not null;comment:业务载荷(JSON)"`
|
||||
// Status + NextRetryAt + RetryCount 共同描述“是否可被调度重试”。
|
||||
Status string `gorm:"column:status;type:varchar(32);not null;index:idx_outbox_status_next,priority:1;comment:pending/published/consumed/dead"`
|
||||
RetryCount int `gorm:"column:retry_count;not null;default:0;comment:已重试次数"`
|
||||
MaxRetry int `gorm:"column:max_retry;not null;default:20;comment:最大重试次数"`
|
||||
NextRetryAt *time.Time `gorm:"column:next_retry_at;index:idx_outbox_status_next,priority:2;comment:下次重试时间"`
|
||||
LastError *string `gorm:"column:last_error;type:text;comment:最后一次错误"`
|
||||
// LastError 记录最近一次失败原因，便于排障和可观测。
|
||||
LastError *string `gorm:"column:last_error;type:text;comment:最后一次错误"`
|
||||
// PublishedAt/ConsumedAt 便于统计“投递延迟”和“消费完成耗时”。
|
||||
PublishedAt *time.Time `gorm:"column:published_at;comment:投递到 Kafka 时间"`
|
||||
ConsumedAt *time.Time `gorm:"column:consumed_at;comment:消费完成时间"`
|
||||
CreatedAt *time.Time `gorm:"column:created_at;autoCreateTime"`
|
||||
@@ -33,7 +47,8 @@ func (AgentOutboxMessage) TableName() string {
|
||||
return "agent_outbox_messages"
|
||||
}
|
||||
|
||||
// ChatHistoryPersistPayload 是“聊天记录持久化”消息体。
|
||||
// ChatHistoryPersistPayload 是“聊天记录持久化”消息的业务载荷。
|
||||
// 注意：该载荷既会被写入 outbox，也会被封装到 Kafka Envelope 中传输。
|
||||
type ChatHistoryPersistPayload struct {
|
||||
UserID int `json:"user_id"`
|
||||
ConversationID string `json:"conversation_id"`
|
||||
|
||||
Reference in New Issue
Block a user