725 lines
14 KiB
Markdown
725 lines
14 KiB
Markdown
# Gomog 用户手册
|
||
|
||
**版本**: v1.0.0-alpha
|
||
**最后更新**: 2026-03-14
|
||
**许可证**: MIT
|
||
|
||
---
|
||
|
||
## 📖 目录
|
||
|
||
1. [简介](#简介)
|
||
2. [快速开始](#快速开始)
|
||
3. [安装与配置](#安装与配置)
|
||
4. [基本使用](#基本使用)
|
||
5. [高级功能](#高级功能)
|
||
6. [最佳实践](#最佳实践)
|
||
7. [故障排查](#故障排查)
|
||
8. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 简介
|
||
|
||
### 什么是 Gomog？
|
||
|
||
Gomog 是一个兼容 MongoDB 风格 API 的内存查询引擎，支持多数据库适配（SQLite、PostgreSQL、达梦 DM8）。它提供了丰富的聚合管道、查询操作符和更新操作符，让你能够以熟悉的方式操作关系型数据库。
|
||
|
||
### 核心特性
|
||
|
||
- ✅ **MongoDB 风格 API**: 熟悉的查询语法，零学习成本
|
||
- ✅ **多数据库支持**: SQLite、PostgreSQL、达梦 DM8
|
||
- ✅ **完整的聚合管道**: 18+ 个聚合阶段，50+ 个聚合表达式
|
||
- ✅ **丰富的查询操作符**: 16+ 个查询操作符
|
||
- ✅ **强大的更新操作符**: 17+ 个更新操作符
|
||
- ✅ **HTTP 和 TCP 双协议**: RESTful API 和 MongoDB 线协议支持
|
||
- ✅ **高性能**: 内存优化，并发安全
|
||
|
||
### 适用场景
|
||
|
||
- 快速原型开发
|
||
- 数据分析和报表
|
||
- 遗留系统现代化
|
||
- 多数据库统一访问层
|
||
- 教学和实验环境
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 下载与安装
|
||
|
||
```bash
|
||
# 从源码编译
|
||
git clone https://github.com/gomog/gomog.git
|
||
cd gomog
|
||
make build
|
||
|
||
# 或使用 Docker
|
||
docker pull gomog:latest
|
||
```
|
||
|
||
### 2. 配置文件
|
||
|
||
复制示例配置文件：
|
||
|
||
```bash
|
||
cp config.yaml.example config.yaml
|
||
```
|
||
|
||
编辑 `config.yaml`：
|
||
|
||
```yaml
|
||
server:
|
||
http_addr: ":8080"
|
||
tcp_addr: ":27017"
|
||
mode: "dev"
|
||
|
||
database:
|
||
type: "sqlite"
|
||
dsn: "gomog.db"
|
||
max_open: 10
|
||
max_idle: 5
|
||
|
||
log:
|
||
level: "info"
|
||
format: "text"
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
# 直接运行
|
||
./bin/gomog -config config.yaml
|
||
|
||
# 或使用 make
|
||
make run
|
||
|
||
# Docker 运行
|
||
docker run -p 8080:8080 -p 27017:27017 gomog:latest
|
||
```
|
||
|
||
### 4. 验证安装
|
||
|
||
```bash
|
||
# HTTP 健康检查
|
||
curl http://localhost:8080/health
|
||
|
||
# 插入测试数据
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"documents": [{"name": "Alice", "age": 30}]}'
|
||
|
||
# 查询数据
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"filter": {"age": {"$gt": 25}}}'
|
||
```
|
||
|
||
---
|
||
|
||
## 安装与配置
|
||
|
||
### 系统要求
|
||
|
||
- **操作系统**: Linux, macOS, Windows
|
||
- **Go 版本**: 1.21+
|
||
- **内存**: 最少 512MB，推荐 1GB+
|
||
- **磁盘**: 最少 100MB 可用空间
|
||
|
||
### 安装方式
|
||
|
||
#### 方式一：源码编译（推荐）
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/gomog/gomog.git
|
||
cd gomog
|
||
|
||
# 编译
|
||
make build
|
||
|
||
# 验证
|
||
./bin/gomog --version
|
||
```
|
||
|
||
#### 方式二：Docker
|
||
|
||
```bash
|
||
# 拉取镜像
|
||
docker pull gomog:latest
|
||
|
||
# 运行
|
||
docker run -d \
|
||
--name gomog \
|
||
-p 8080:8080 \
|
||
-p 27017:27017 \
|
||
-v $(pwd)/data:/data \
|
||
gomog:latest
|
||
```
|
||
|
||
#### 方式三：包管理器（待提供）
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt install gomog
|
||
|
||
# CentOS/RHEL
|
||
sudo yum install gomog
|
||
|
||
# macOS (Homebrew)
|
||
brew install gomog
|
||
```
|
||
|
||
### 配置详解
|
||
|
||
#### 服务器配置
|
||
|
||
```yaml
|
||
server:
|
||
# HTTP 监听地址
|
||
# 格式：[host]:port
|
||
# 默认：":8080"
|
||
http_addr: ":8080"
|
||
|
||
# TCP 监听地址（MongoDB 线协议）
|
||
# 格式：[host]:port
|
||
# 默认：":27017"
|
||
tcp_addr: ":27017"
|
||
|
||
# 运行模式
|
||
# 可选值：dev, prod
|
||
# dev: 详细日志，调试信息
|
||
# prod: 精简日志，性能优化
|
||
mode: "dev"
|
||
```
|
||
|
||
#### 数据库配置
|
||
|
||
```yaml
|
||
database:
|
||
# 数据库类型
|
||
# 可选值：sqlite, postgres, dm8
|
||
type: "sqlite"
|
||
|
||
# 数据源名称
|
||
# SQLite: 文件路径或 :memory:
|
||
# PostgreSQL: postgresql://user:pass@host:port/dbname?sslmode=disable
|
||
# DM8: dm://user:pass@host:port/dbname
|
||
dsn: "gomog.db"
|
||
|
||
# 最大打开连接数
|
||
# 默认：10
|
||
max_open: 10
|
||
|
||
# 最大空闲连接数
|
||
# 默认：5
|
||
max_idle: 5
|
||
|
||
# 连接最大生命周期（可选）
|
||
# 格式：时间 Duration 字符串
|
||
# 默认："4h"
|
||
max_lifetime: "4h"
|
||
```
|
||
|
||
#### 日志配置
|
||
|
||
```yaml
|
||
log:
|
||
# 日志级别
|
||
# 可选值：debug, info, warn, error
|
||
# debug: 所有日志
|
||
# info: 常规信息
|
||
# warn: 警告信息
|
||
# error: 错误信息
|
||
level: "info"
|
||
|
||
# 日志格式
|
||
# 可选值：text, json
|
||
# text: 人类可读格式
|
||
# json: 结构化 JSON 格式
|
||
format: "text"
|
||
|
||
# 日志输出文件（可选）
|
||
# 默认：stdout
|
||
output: "/var/log/gomog/gomog.log"
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
Gomog 支持通过环境变量覆盖配置文件：
|
||
|
||
| 环境变量 | 配置项 | 示例 |
|
||
|---------|--------|------|
|
||
| `GOMOG_HTTP_ADDR` | server.http_addr | `GOMOG_HTTP_ADDR=:9000` |
|
||
| `GOMOG_TCP_ADDR` | server.tcp_addr | `GOMOG_TCP_ADDR=:27018` |
|
||
| `GOMOG_DB_TYPE` | database.type | `GOMOG_DB_TYPE=postgres` |
|
||
| `GOMOG_DB_DSN` | database.dsn | `GOMOG_DB_DSN=mydb.db` |
|
||
| `GOMOG_LOG_LEVEL` | log.level | `GOMOG_LOG_LEVEL=debug` |
|
||
|
||
---
|
||
|
||
## 基本使用
|
||
|
||
### 数据库和集合管理
|
||
|
||
#### 创建数据库
|
||
|
||
Gomog 会自动创建不存在的数据库，无需手动创建。
|
||
|
||
#### 创建集合
|
||
|
||
同样，集合会在首次插入数据时自动创建。
|
||
|
||
#### 列出所有数据库
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/admin/listDatabases
|
||
```
|
||
|
||
#### 列出所有集合
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/{database}/listCollections
|
||
```
|
||
|
||
### CRUD 操作
|
||
|
||
#### 插入（Insert）
|
||
|
||
```bash
|
||
# 单条插入
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"documents": [{"name": "Alice", "age": 30}]}'
|
||
|
||
# 批量插入
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/insert \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"documents": [
|
||
{"name": "Bob", "age": 25},
|
||
{"name": "Charlie", "age": 35}
|
||
]
|
||
}'
|
||
```
|
||
|
||
#### 查询（Find）
|
||
|
||
```bash
|
||
# 查询所有
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
|
||
-H "Content-Type: application/json" \
|
||
-d '{}'
|
||
|
||
# 条件查询
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"filter": {"age": {"$gt": 28}}}'
|
||
|
||
# 投影（选择字段）
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/find \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {"age": {"$gt": 28}},
|
||
"projection": {"name": 1, "age": 1}
|
||
}'
|
||
```
|
||
|
||
#### 更新（Update）
|
||
|
||
```bash
|
||
# 更新单个文档
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {"name": "Alice"},
|
||
"update": {"$set": {"age": 31}}
|
||
}'
|
||
|
||
# 更新多个文档
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {},
|
||
"update": {"$inc": {"age": 1}},
|
||
"multi": true
|
||
}'
|
||
|
||
# Upsert（不存在则插入）
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/update \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"filter": {"name": "David"},
|
||
"update": {"$setOnInsert": {"name": "David", "age": 28}},
|
||
"upsert": true
|
||
}'
|
||
```
|
||
|
||
#### 删除（Delete）
|
||
|
||
```bash
|
||
# 删除单个文档
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"filter": {"name": "Alice"}}'
|
||
|
||
# 删除多个文档
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/delete \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"filter": {"age": {"$lt": 30}}, "multi": true}'
|
||
```
|
||
|
||
### 聚合操作
|
||
|
||
```bash
|
||
# 简单聚合
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/aggregate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pipeline": [
|
||
{"$match": {"age": {"$gte": 30}}},
|
||
{"$group": {
|
||
"_id": "$department",
|
||
"count": {"$sum": 1},
|
||
"avgAge": {"$avg": "$age"}
|
||
}}
|
||
]
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 高级功能
|
||
|
||
### 聚合管道
|
||
|
||
Gomog 支持完整的 MongoDB 聚合管道，包括：
|
||
|
||
#### 1. 数据过滤
|
||
|
||
```json
|
||
{
|
||
"pipeline": [
|
||
{"$match": {"status": "active"}},
|
||
{"$limit": 10},
|
||
{"$skip": 5}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 2. 数据转换
|
||
|
||
```json
|
||
{
|
||
"pipeline": [
|
||
{"$addFields": {"fullName": {"$concat": ["$firstName", " ", "$lastName"]}}},
|
||
{"$project": {"_id": 0, "fullName": 1, "email": 1}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3. 数据分组
|
||
|
||
```json
|
||
{
|
||
"pipeline": [
|
||
{"$group": {
|
||
"_id": "$category",
|
||
"total": {"$sum": "$amount"},
|
||
"average": {"$avg": "$price"}
|
||
}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 4. 数据排序
|
||
|
||
```json
|
||
{
|
||
"pipeline": [
|
||
{"$sort": {"created_at": -1}},
|
||
{"$limit": 10}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 5. 关联查询（Lookup）
|
||
|
||
```json
|
||
{
|
||
"pipeline": [
|
||
{"$lookup": {
|
||
"from": "orders",
|
||
"localField": "_id",
|
||
"foreignField": "userId",
|
||
"as": "orders"
|
||
}}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 文本搜索
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/articles/aggregate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pipeline": [
|
||
{"$match": {"$text": {"$search": "database performance"}}},
|
||
{"$sort": {"score": {"$meta": "textScore"}}}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 窗口函数
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/sales/aggregate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pipeline": [{
|
||
"$setWindowFields": {
|
||
"partitionBy": "$region",
|
||
"sortBy": {"date": 1},
|
||
"output": {
|
||
"runningTotal": {
|
||
"$sum": "$amount",
|
||
"window": {"documents": ["unbounded", "current"]}
|
||
},
|
||
"rank": {"$documentNumber": {}}
|
||
}
|
||
}
|
||
}]
|
||
}'
|
||
```
|
||
|
||
### 递归查找
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/testdb/orgs/aggregate \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"pipeline": [{
|
||
"$graphLookup": {
|
||
"from": "orgs",
|
||
"startWith": "$parentId",
|
||
"connectFromField": "_id",
|
||
"connectToField": "parentId",
|
||
"as": "subOrgs",
|
||
"maxDepth": 5
|
||
}
|
||
}]
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 性能优化
|
||
|
||
#### 1. 合理使用索引
|
||
|
||
```bash
|
||
# 为常用查询字段创建索引
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/createIndex \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"keys": {"email": 1}, "unique": true}'
|
||
```
|
||
|
||
#### 2. 避免全表扫描
|
||
|
||
```bash
|
||
# ❌ 不推荐：全表扫描
|
||
{"filter": {"$expr": {"$gt": ["$age", 25]}}}
|
||
|
||
# ✅ 推荐：使用索引
|
||
{"filter": {"age": {"$gt": 25}}}
|
||
```
|
||
|
||
#### 3. 限制返回结果
|
||
|
||
```bash
|
||
# 总是使用 limit 限制返回数量
|
||
{"limit": 100}
|
||
```
|
||
|
||
#### 4. 使用投影减少数据传输
|
||
|
||
```bash
|
||
# 只返回需要的字段
|
||
{"projection": {"name": 1, "email": 1}}
|
||
```
|
||
|
||
### 数据安全
|
||
|
||
#### 1. 输入验证
|
||
|
||
始终在应用层验证用户输入，不要完全依赖数据库验证。
|
||
|
||
#### 2. 参数化查询
|
||
|
||
使用 Gomog 的参数化机制，避免注入攻击。
|
||
|
||
#### 3. 权限控制
|
||
|
||
在生产环境中使用数据库的权限控制机制。
|
||
|
||
### 监控与日志
|
||
|
||
#### 1. 启用慢查询日志
|
||
|
||
```yaml
|
||
log:
|
||
level: "debug"
|
||
slow_query_threshold: "100ms"
|
||
```
|
||
|
||
#### 2. 监控关键指标
|
||
|
||
- QPS（每秒查询数）
|
||
- 平均响应时间
|
||
- 错误率
|
||
- 连接池使用率
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
|
||
#### 1. 无法启动服务
|
||
|
||
**症状**: 启动时报错 "address already in use"
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查端口占用
|
||
lsof -i :8080
|
||
lsof -i :27017
|
||
|
||
# 修改配置文件使用其他端口
|
||
server:
|
||
http_addr: ":8081"
|
||
tcp_addr: ":27018"
|
||
```
|
||
|
||
#### 2. 数据库连接失败
|
||
|
||
**症状**: "failed to connect to database"
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查数据库配置
|
||
cat config.yaml | grep -A 5 database
|
||
|
||
# 验证数据库服务是否运行
|
||
# PostgreSQL
|
||
pg_isready -h localhost -p 5432
|
||
|
||
# SQLite
|
||
ls -la gomog.db
|
||
```
|
||
|
||
#### 3. 查询性能慢
|
||
|
||
**症状**: 查询响应时间超过预期
|
||
|
||
**解决**:
|
||
```bash
|
||
# 1. 查看执行计划
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/explain \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"filter": {"age": {"$gt": 25}}}'
|
||
|
||
# 2. 添加索引
|
||
curl -X POST http://localhost:8080/api/v1/testdb/users/createIndex \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"keys": {"age": 1}}'
|
||
|
||
# 3. 优化查询
|
||
# 避免使用 $expr，改用原生操作符
|
||
```
|
||
|
||
#### 4. 内存不足
|
||
|
||
**症状**: OOM killer 杀死进程
|
||
|
||
**解决**:
|
||
```yaml
|
||
# 限制连接池大小
|
||
database:
|
||
max_open: 5
|
||
max_idle: 2
|
||
```
|
||
|
||
### 日志分析
|
||
|
||
#### 查看日志
|
||
|
||
```bash
|
||
# 实时查看日志
|
||
tail -f /var/log/gomog/gomog.log
|
||
|
||
# 搜索错误
|
||
grep "ERROR" /var/log/gomog/gomog.log
|
||
```
|
||
|
||
#### 日志级别说明
|
||
|
||
- **DEBUG**: 详细调试信息，包含所有查询和响应
|
||
- **INFO**: 常规运行信息
|
||
- **WARN**: 警告信息，不影响正常运行
|
||
- **ERROR**: 错误信息，需要关注
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: Gomog 与 MongoDB 有什么区别？
|
||
|
||
A: Gomog 是一个兼容 MongoDB 风格 API 的查询引擎，底层可以使用 SQLite、PostgreSQL 等关系型数据库。它不是 MongoDB 的直接替代品，而是提供了一种熟悉的方式来操作关系型数据库。
|
||
|
||
### Q: 支持哪些 MongoDB 操作符？
|
||
|
||
A: Gomog 支持 16+ 个查询操作符、17+ 个更新操作符、18+ 个聚合阶段和 50+ 个聚合表达式。详见 [API 参考文档](API_REFERENCE.md)。
|
||
|
||
### Q: 如何在生产环境使用？
|
||
|
||
A:
|
||
1. 设置 `mode: "prod"`
|
||
2. 配置合适的连接池大小
|
||
3. 启用日志持久化
|
||
4. 配置监控告警
|
||
5. 定期备份数据
|
||
|
||
### Q: 是否支持事务？
|
||
|
||
A: 取决于底层数据库。PostgreSQL 和达梦 DM8 支持事务，SQLite 支持有限的事务。
|
||
|
||
### Q: 如何备份数据？
|
||
|
||
A:
|
||
- **SQLite**: 直接复制 `.db` 文件
|
||
- **PostgreSQL**: 使用 `pg_dump`
|
||
- **DM8**: 使用 DM 的备份工具
|
||
|
||
### Q: 性能如何？
|
||
|
||
A: 对于中小规模数据集（<100 万条记录），Gomog 能提供亚秒级的查询响应。对于大规模数据，建议使用原生数据库客户端以获得最佳性能。
|
||
|
||
---
|
||
|
||
## 获取帮助
|
||
|
||
- **文档**: `/manual` 目录
|
||
- **示例**: [API_EXAMPLES.md](../doc/API_EXAMPLES.md)
|
||
- **问题反馈**: GitHub Issues
|
||
- **社区讨论**: GitHub Discussions
|
||
|
||
---
|
||
|
||
**维护者**: Gomog Team
|
||
**许可证**: MIT
|