rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
05af5ebcbcb4734585fea49cd57d916cb6e8d2d3
gochat/README.md
T
rogee 1535e6cd55 Decouple frontend from Rails, establish pnpm workspace dev workflow 
Strip the Chatwoot frontend down to a standalone Vite + Vue 3 SPA that talks
directly to the GoChat Go backend — no Ruby/Rails required.

Deleted from frontend/ (all Rails-only):
- Ruby: Gemfile, Gemfile.lock, config.ru, Capfile, Rakefile, bin/ (binstubs),
  config/ (application/boot/environment/routes/initializers/environments/locales),
  app/helpers/ (*.rb), app/views/ (ERB/jbuilder), app/assets/ (administrate scss)
- Enterprise overlay (enterprise/ — pure Ruby/jbuilder, zero JS)
- Infra: Procfile*, docker-compose*, docker/, deployment/, swagger/, .circleci/,
  .devcontainer/, .qlty/, .codegraph/, .windsurf/, .github/, .vscode/, .husky/
- Lint/config: .rubocop.yml, .scss-lint.yml, .rspec, rubocop/, .bundler-audit.yml,
  .annotaterb.yml, .all-contributorsrc, crowdin.yml, histoire.config.ts, etc.
- Stale frontend/pnpm-lock.yaml (replaced by root workspace lockfile)

Kept (frontend build essentials):
- app/javascript/ (all Vue SPA source — dashboard/widget/sdk/portal/superadmin/survey/v3)
- package.json, vite.config.ts, tailwind.config.js, postcss.config.js
- theme/, vitest.setup.js, .prettierrc

Key decoupling changes:
- vite.config.ts: removed vite-plugin-ruby, added explicit rollupOptions.input
  for all 7 entrypoints + dev-server proxy (/api,/platform,/cable,/health → GoChat)
- index.html: created static SPA entry that injects window.chatwootConfig /
  window.globalConfig (previously done by Rails ERB vueapp.html.erb)
- package.json: renamed @gochat/frontend, removed vite-plugin-ruby/histoire/husky,
  scripts now use plain vite dev/build
- tailwind.config.js: removed enterprise ERB content paths
- markdownEmbeds.js: relocated markdown_embeds.yml into app/javascript/dashboard/config/

Root pnpm workspace:
- package.json: dev:backend (air), dev:frontend (vite), dev (concurrently)
- pnpm-workspace.yaml: frontend as workspace package
- .gitignore: node_modules/, frontend/dist/, frontend build artifacts

Verified: pnpm install + vite build succeeds (4446 modules, all 7 entrypoints
produce JS+CSS chunks in dist/).
2026-07-07 15:37:24 +08:00

230 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/
```
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](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
Reference in New Issue View Git Blame Copy Permalink