191 lines
5.7 KiB
Markdown
191 lines
5.7 KiB
Markdown
# GoChat
|
||
|
||
> 开源企业级即时通讯平台，参考 Chatwoot 架构，Go 语言实现。
|
||
|
||
## 项目概览
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| Go 源码文件 | 299 |
|
||
| 测试文件 | 83 |
|
||
| 测试用例 | 141+ |
|
||
| API 路由 | 106 |
|
||
| Go 包 | 42 |
|
||
| 安全模块 | 14 |
|
||
|
||
## 架构
|
||
|
||
GoChat 采用 **分层架构** + **模块化设计**：
|
||
|
||
```
|
||
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 自定义规则
|
||
tests/
|
||
e2e/ # 端到端测试（Auth/AccountCRUD/CRM）
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置依赖
|
||
|
||
- Go 1.25+
|
||
- PostgreSQL 16（带 pgvector）
|
||
- Redis 7+
|
||
- Docker（可选）
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/gochat/gochat.git
|
||
cd gochat
|
||
|
||
# 安装依赖
|
||
go mod download
|
||
|
||
# 配置环境
|
||
cp .env.example .env
|
||
# 编辑 .env 配置数据库、Redis、JWT等
|
||
|
||
# 运行服务
|
||
go run cmd/server/main.go
|
||
|
||
# 运行测试（SQLite模式，无需PG）
|
||
GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...
|
||
|
||
# 运行测试（PG模式）
|
||
go test -v -race ./...
|
||
|
||
# 运行e2e测试
|
||
go test -v ./tests/e2e/...
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t gochat/gochat:latest .
|
||
|
||
# 使用 docker-compose
|
||
docker compose up -d
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
GoChat 使用 **Viper 多环境叠加**机制：
|
||
|
||
- `configs/default.yaml` — 默认配置
|
||
- `configs/production.yaml` — 生产覆盖
|
||
- `configs/development.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 全链路 |
|
||
| 安全测试 | 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](docs/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](.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 |
|
||
|
||
## 文档
|
||
|
||
- [架构设计](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 |