rogee
321c61aaae
Copy the Chatwoot (v4.14.0) frontend runnable subset into frontend/ for customization: - app/javascript/ (Vue SPA: dashboard, widget, sdk, portal, superadmin) - app/views/ (ERB templates for vite-plugin-ruby entrypoint resolution) - app/helpers/, app/assets/ (Rails view helpers, static assets) - enterprise/ (Enterprise edition frontend overlay) - config/vite.json, vite.config.ts, bin/vite (Vite-Rails toolchain) - package.json, pnpm-lock.yaml, tailwind/postcss/eslint configs - Gemfile, Gemfile.lock (vite_rails gem for bin/vite binstub) Excluded Rails backend: controllers, models, services, jobs, mailers, policies, db, lib, spec, public, node_modules. Update references to the new frontend location: - .gitignore: exclude frontend build artifacts (node_modules, tmp, packs), keep frontend/bin/ and frontend/vendor/ via negation - backend/scripts/parity_frontend_smoke.sh: CHATWOOT_DIR default reference/chatwoot -> ../frontend - backend/scripts/parity_frontend_browser_smoke.mjs: same default update - AGENTS.md: add frontend section with Rails/Vite coupling notes - README: architecture tree includes frontend/
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 前端（vendor 过来后续定制）
app/javascript/ # Vue SPA 源码（dashboard/widget/sdk/portal/superadmin）
app/views/ # ERB 模板（vite-plugin-ruby entrypoint 解析依赖）
enterprise/ # 企业版前端覆盖层
config/vite.json # Vite-Rails 桥接配置
package.json # 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。
环境配置
GoChat 使用 Viper 多环境叠加机制：
backend/configs/config.yaml— 默认配置backend/configs/config.prod.yaml— 生产覆盖backend/configs/config.dev.yaml— 开发覆盖.env— 本地覆盖（最高优先级）- 11 个字段支持 热加载（无需重启）
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 |
健康检查 |
测试策略
| 层级 | 工具 | 覆盖 |
|---|---|---|
| 单元测试 | 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
CI/CD
GitHub Actions 5阶段流水线：
- Test & Lint: lint + vet + 单元/集成/e2e/benchmark（PG+SQLite矩阵）
- Security Scan: gosec + govulncheck + Trivy
- Build: Docker多平台镜像 + GHCR推送
- Helm Validate: K8s Helm chart lint + kubeconform
- Deploy: Staging（develop分支）+ Production（release分支）
技术栈
| 组件 | 技术 |
|---|---|
| 语言 | 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