GoChat

开源企业级即时通讯平台，参考 Chatwoot 架构，Go 语言实现。

项目概览

指标	数值
Go 源码文件	299
测试文件	83
测试用例	141+
API 路由	106
Go 包	42
安全模块	14

架构

GoChat 采用 分层架构 + 模块化设计：

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/

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.prod.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 全链路
安全测试	golangci-lint + gosec + govulncheck	代码安全扫描
性能测试	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

CI/CD

GitHub Actions 5阶段流水线：

1. Test & Lint: lint + vet + 单元/集成/e2e/benchmark（PG+SQLite矩阵）
2. Security Scan: gosec + govulncheck + Trivy
3. Build: Docker多平台镜像 + GHCR推送
4. Helm Validate: K8s Helm chart lint + kubeconform
5. Deploy: Staging（develop分支）+ Production（release分支）

详见 .github/workflows/ci.yml

技术栈

组件	技术
语言	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
K8s	Helm chart

文档

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

License

MIT