backend/                # Go 后端（单仓库 monorepo 子目录）
  cmd/                  # 入口（migrate, server）
  internal/
    app/                # 应用启动、graceful shutdown
    auth/               # JWT认证、Refresh Token、TOTP
    autoassignment/     # 智能分配
    channel/provider/   # 渠道抽象层（Telegram/WebWidget/Email）
    config/             # Viper多环境热加载配置
    handler/api/v1/     # HTTP Handler（Gin，104+路由）
    llm/                # CaptainAI LLM Provider（OpenAI/Ollama/volcengine）
    middleware/         # Auth/CORS/RateLimiting/AccountScope/InputValidation
    model/              # GORM 数据模型（Base/Account/User/Contact/Inbox等）
    pubsub/             # Redis Pub/Sub
    repository/         # 数据访问层（21 repo）
    service/            # 业务逻辑层
    ws/                 # WebSocket Hub（/cable）
  pkg/
    crypto/             # bcrypt Hash/Check
    validation/         # go-playground/validator/v10 自定义规则
  configs/              # 多环境配置（config.yaml + config.{env}.yaml）
  migrations/           # SQL 迁移文件
  docs/                 # Swagger/OpenAPI 生成代码
  scripts/              # 迁移、种子、健康检查等脚本
  tests/
    e2e/                # 端到端测试（Auth/AccountCRUD/CRM）
frontend/               # Chatwoot Vue 3 前端（已从 Rails 解耦，独立 Vite SPA）
  app/javascript/       # Vue SPA 源码（dashboard/widget/sdk/portal/superadmin）
  index.html            # 静态入口（注入 window.chatwootConfig）
  vite.config.ts        # 标准 Vite 配置（dev server 代理 API 到 GoChat 后端）
  package.json          # @gochat/frontend（pnpm + Vite + Vue 3）
deploy/                 # 部署相关
  docker/               # Dockerfile + docker-compose（dev/prod/test）
  quickstart/           # 本地/UAT 一键启动 Compose 栈
  fluentd/              # 日志收集配置
docs/                   # 项目文档（架构、需求、计划、报告）

快速开始

前置依赖

Go 1.25+
PostgreSQL 16（带 pgvector）
Redis 7+
Docker（可选）

本地开发

# 克隆项目
git clone https://github.com/gochat/gochat.git
cd gochat

# 安装依赖（在 backend/ 下）
cd backend
go mod download

# 配置环境（从仓库根目录复制）
cp ../.env.example ../.env
# 编辑 .env 配置数据库、Redis、JWT等

# 运行服务
go run cmd/gochat/main.go serve

# 运行测试（SQLite模式，无需PG）
GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...

# 运行测试（PG模式）
go test -v -race ./...

# 运行e2e测试
go test -v ./tests/e2e/...

Docker 部署

# 本地/UAT 快速启动：GoChat + PostgreSQL/pgvector + Redis + Meilisearch + Mailhog
cd deploy/quickstart
cp .env.example .env
docker compose up -d --build

# 可选：初始化演示账号和业务数据
docker compose --profile seed run --rm seed

详见 deploy/quickstart/README.md。

前端开发

前端已从 Chatwoot 的 Rails 耦合中解耦，现为独立的 Vite + Vue 3 SPA，直连 GoChat 后端。

# 仓库根目录统一启动
pnpm install              # 安装所有 workspace 依赖
pnpm dev:backend          # 启动 Go 后端（air 热重载，端口 3000）
pnpm dev:frontend         # 启动 Vite dev server（端口 3036，API 代理到 :3000）
pnpm dev                  # 同时启动前后端

# 单独构建前端
pnpm build:frontend       # 生产构建 → frontend/dist/

# 校验前端可重复交付基线
pnpm verify:frontend:delivery # frozen install + 构建产物检查 + 生产依赖 high/critical 漏洞扫描

前端交付以仓库提交的 pnpm-lock.yaml 为准；依赖变更必须同步提交 lockfile，交付前运行上述校验。无锁重新解析会随 semver、peer 和可选平台依赖变化，不作为完整依赖图一致性目标。

Vite dev server 会将 /api、/platform、/cable、/health 代理到 GoChat 后端（默认 http://127.0.0.1:3000，可通过 VITE_API_HOST 环境变量覆盖）。

环境配置

GoChat 使用 Viper 多环境叠加机制：

backend/configs/config.yaml — 默认配置
backend/configs/config.production.yaml — 生产覆盖
backend/configs/config.dev.yaml — 开发覆盖
.env — 本地覆盖（最高优先级）
11 个字段支持 热加载（无需重启）

详见 PHASE2_P0_ENV_CONFIG.md

API 路由

核心 API 路由106个，覆盖 Chatwoot API 97%+：

模块	路由前缀	说明
Auth	`/api/v1/auth/`	登录、注册、刷新、TOTP
Accounts	`/api/v1/accounts/`	企业账号 CRUD
Contacts	`/api/v1/accounts/:id/contacts/`	客户联系人 CRM
Inboxes	`/api/v1/accounts/:id/inboxes/`	渠道收件箱
Conversations	`/api/v1/accounts/:id/conversations/`	会话管理
Messages	`/api/v1/accounts/:id/conversations/:conversation_id/messages/`	消息
CaptainAI	`/api/v1/accounts/:id/captain/`	AI助手、文档、场景
Reports	`/api/v1/accounts/:id/reports/`	报表统计
Teams	`/api/v1/accounts/:id/teams/`	团队管理
WebWidget	`/api/v1/accounts/:id/inboxes/:inbox_id/web_widget/`	网页客服
Telegram	`/api/v1/accounts/:id/telegram/`	Telegram渠道
WebSocket	`/cable`	实时消息推送
Health	`/health`	健康检查

详见 API_COVERAGE_REPORT.md

测试策略

层级	工具	覆盖
单元测试	Go test + testify	Service/Repository/Model/Auth/Config
集成测试	Go test + GORM	Service↔Repository↔DB
E2E测试	httptest + Gin	Handler↔Service↔DB 全链路
性能测试	Go benchmark	Service/crypto基准
DB双模式	PG + SQLite	`GOCHAT_TEST_DB` 自动切换

PG-only功能（vector搜索等）使用 skipIfSQLite 自动跳过。

安全

Rate Limiting: per-IP 令牌桶（golang.org/x/time/rate）
输入验证: go-playground/validator/v10 + 4自定义规则
SQL注入防护: GORM参数化查询
CORS: 生产白名单配置
JWT: RS256签名 + Refresh Token Rotation
TOTP: 双因子认证
Password: bcrypt hash

详见 SECURITY_AUDIT_REPORT.md

技术栈

组件	技术
语言	Go 1.25
HTTP框架	Gin v1.10
ORM	GORM v2
数据库	PostgreSQL 16 + pgvector
缓存	Redis 7
认证	JWT (RS256) + bcrypt + TOTP
配置	Viper + .env
WebSocket	Gorilla WebSocket
验证	go-playground/validator/v10
限流	golang.org/x/time/rate
LLM	OpenAI / Ollama / volcengine
容器	Docker + Buildx
部署	Docker Compose

文档

架构设计 — 架构总览、对比分析
API覆盖报告 — 106路由 vs Chatwoot
安全审计 — 14安全模块
性能基准 — benchmark数据
集成验证 — 模块集成测试
环境配置 — Viper热加载
交接文档 — 项目交接
阶段计划 — Phase 2规划

License

MIT

README.md Unescape Escape

GoChat

项目概览

架构