223 lines
7.6 KiB
Markdown
223 lines
7.6 KiB
Markdown
# 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（可选）
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 克隆项目
|
||
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 部署
|
||
|
||
```bash
|
||
# 本地/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](deploy/quickstart/README.md)。
|
||
|
||
### 前端开发
|
||
|
||
前端已从 Chatwoot 的 Rails 耦合中解耦，现为独立的 Vite + Vue 3 SPA，直连 GoChat 后端。
|
||
|
||
```bash
|
||
# 仓库根目录统一启动
|
||
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](docs/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](docs/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](docs/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 |
|
||
|
||
## 文档
|
||
|
||
- [架构设计](docs/architecture/) — 架构总览、对比分析
|
||
- [API覆盖报告](docs/API_COVERAGE_REPORT.md) — 106路由 vs Chatwoot
|
||
- [安全审计](docs/SECURITY_AUDIT_REPORT.md) — 14安全模块
|
||
- [性能基准](docs/PERFORMANCE_BENCHMARK.md) — benchmark数据
|
||
- [集成验证](docs/INTEGRATION_VERIFICATION_REPORT.md) — 模块集成测试
|
||
- [环境配置](docs/PHASE2_P0_ENV_CONFIG.md) — Viper热加载
|
||
- [交接文档](docs/HANDOVER_DOCUMENT.md) — 项目交接
|
||
- [阶段计划](docs/PHASE2_PLAN.md) — Phase 2规划
|
||
|
||
## License
|
||
|
||
MIT
|