docs: add multi-language documentation (ru, fa, zh, tr, ar)

2026-05-07 23:42:55 +03:00
parent abb382c419
commit e9d3c7e9de
157 changed files with 14339 additions and 0 deletions
@@ -0,0 +1,62 @@
+# 二进制协议 API
+
+用于高性能客户端连接的低级 wire 协议。
+
+## 消息格式
+
+所有消息使用大端字节序：
+
+```
+┌────────┬────────┬────────┬────────┬─────────────┐
+│ Length │  Type  │  Seq   │ Status │   Payload   │
+│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │  N bytes    │
+└────────┴────────┴────────┴────────┴─────────────┘
+```
+
+## 消息类型
+
+### Query (0x01)
+
+```nim
+let msg = makeQueryMessage(seq, "SELECT * FROM users")
+```
+
+### Insert (0x02)
+
+```nim
+let msg = makeInsertMessage(seq, "users", data)
+```
+
+### Update (0x03)
+
+```nim
+let msg = makeUpdateMessage(seq, "users", updates, where)
+```
+
+### Delete (0x04)
+
+```nim
+let msg = makeDeleteMessage(seq, "users", where)
+```
+
+### Ready (0x05)
+
+```nim
+let msg = makeReadyMessage(seq)
+```
+
+### Error (0x06)
+
+```nim
+let msg = makeErrorMessage(seq, code, message)
+```
+
+## 响应码
+
+| 代码 | 名称 | 描述 |
+|------|------|------|
+| 0x00 | OK | 成功 |
+| 0x01 | ERROR | 一般错误 |
+| 0x02 | AUTH_REQUIRED | 需要认证 |
+| 0x03 | INVALID_QUERY | 查询语法错误 |
+| 0x04 | NOT_FOUND | 资源未找到 |
@@ -0,0 +1,62 @@
+# HTTP/REST API
+
+用于 Web 应用程序的基于 JSON 的 REST API。
+
+## Base URL
+
+```
+http://localhost:9470/api
+```
+
+## 端点
+
+### GET /api/users
+
+列出所有用户：
+
+```bash
+curl http://localhost:9470/api/users
+```
+
+### GET /api/users/:id
+
+按 ID 获取用户：
+
+```bash
+curl http://localhost:9470/api/users/1
+```
+
+### POST /api/users
+
+创建用户：
+
+```bash
+curl -X POST http://localhost:9470/api/users \
+  -d '{"name": "Charlie", "age": 35}'
+```
+
+### PUT /api/users/:id
+
+更新用户：
+
+```bash
+curl -X PUT http://localhost:9470/api/users/1 \
+  -d '{"name": "Alice", "age": 31}'
+```
+
+### DELETE /api/users/:id
+
+删除用户：
+
+```bash
+curl -X DELETE http://localhost:9470/api/users/1
+```
+
+## 查询端点
+
+通过 HTTP 执行 BaraQL 查询：
+
+```bash
+curl -X POST http://localhost:9470/api/query \
+  -d '{"sql": "SELECT * FROM users WHERE age > 18"}'
+```
@@ -0,0 +1,67 @@
+# WebSocket API
+
+用于实时数据流和推送通知的全双工流。
+
+## 连接
+
+```
+ws://localhost:9471/ws
+```
+
+## 客户端示例
+
+```javascript
+const ws = new WebSocket('ws://localhost:9471/ws');
+
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'query',
+    sql: 'SELECT * FROM users'
+  }));
+};
+
+ws.onmessage = (event) => {
+  console.log('Received:', JSON.parse(event.data));
+};
+```
+
+## 消息格式
+
+```json
+{
+  "type": "query",
+  "id": "uuid",
+  "sql": "SELECT * FROM users"
+}
+```
+
+## 消息类型
+
+### 查询请求
+
+```json
+{
+  "type": "query",
+  "id": "123",
+  "sql": "SELECT * FROM users"
+}
+```
+
+### 查询响应
+
+```json
+{
+  "type": "result",
+  "id": "123",
+  "data": [{"id": 1, "name": "Alice"}]
+}
+```
+
+### 订阅
+
+```json
+{
+  "type": "subscribe",
+  "table": "users"
+}
+```
@@ -0,0 +1,197 @@
+# BaraDB 架构
+
+## 概述
+
+BaraDB 是一个**多模态数据库引擎**，使用 Nim 编写，将文档 (KV)、图、向量、列式和全文搜索存储整合在单一引擎中，使用统一的查询语言 **BaraQL**。
+
+## 分层架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. 客户端层                                             │
+│    二进制协议 │ HTTP/REST │ WebSocket │ 嵌入式            │
+├─────────────────────────────────────────────────────────┤
+│ 2. 查询层 (BaraQL)                                      │
+│    词法分析 → 解析 → AST → IR → 优化器 → 代码生成         │
+├─────────────────────────────────────────────────────────┤
+│ 3. 执行引擎                                             │
+│    文档 │ 图 │ 向量 │ 列式 │ FTS                         │
+├─────────────────────────────────────────────────────────┤
+│ 4. 存储层                                               │
+│    LSM-Tree │ B-Tree │ WAL │ Bloom │ 压缩 │ 缓存         │
+├─────────────────────────────────────────────────────────┤
+│ 5. 分布式                                               │
+│    Raft 共识 │ 分片 │ 复制 │ Gossip                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 第1层: 客户端层
+
+多种通信协议:
+
+- **二进制协议** (`protocol/wire.nim`): 高效的 big-endian 二进制协议，包含 16 种消息类型
+- **HTTP/REST** (`core/httpserver.nim`): 基于 JSON 的 REST API，支持多线程
+- **WebSocket** (`core/websocket.nim`): 全双工流式传输
+- **嵌入式** (`storage/lsm.nim`): 进程内直接访问
+
+### 连接管理
+
+- **连接池** (`protocol/pool.nim`): 最小/最大连接限制，空闲超时
+- **限流** (`protocol/ratelimit.nim`): Token-bucket 全局限流和每客户端限流
+- **认证** (`protocol/auth.nim`): HMAC-SHA256 的 JWT 和基于角色的访问
+- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3，自动生成证书
+
+## 第2层: 查询层 (BaraQL)
+
+BaraQL 处理管道:
+
+1. **词法分析器** (`query/lexer.nim`): 将输入标记化为 80+ 种标记类型
+2. **解析器** (`query/parser.nim`): 递归下降解析器，生成 AST
+3. **AST** (`query/ast.nim`): 300+ 行代码，覆盖 25+ 种节点类型
+4. **IR** (`query/ir.nim`): 用于执行计划的中间表示
+5. **优化器** (`query/adaptive.nim`): 自适应跨模态查询优化
+6. **代码生成** (`query/codegen.nim`): 将 IR 转换为存储操作
+7. **执行器** (`query/executor.nim`): 并行执行计划
+
+### 跨模态规划
+
+优化器 (`query/adaptive.nim`) 确定跨引擎的执行顺序:
+
+```
+1. 估算每个谓词的选择性
+2. 将选择性最高的谓词首先推送到其引擎
+3. 使用 Bloom 过滤器进行 KV 查找
+4. 并行化独立分支
+5. 流式传输结果以避免物化
+```
+
+## 第3层: 执行引擎
+
+### 文档/KV 引擎
+- **LSM-Tree** (`storage/lsm.nim`): 写优化的存储，包含 MemTable、WAL、SSTables
+- **B-Tree 索引** (`storage/btree.nim`): 用于范围扫描的有序索引，支持 COW
+
+### 向量引擎 (`vector/`)
+- **HNSW 索引** (`vector/engine.nim`): 分层可导航小世界图
+- **IVF-PQ 索引** (`vector/engine.nim`): 倒排文件索引，带乘积量化
+- **SIMD 操作** (`vector/simd.nim`): AVX2 优化的距离计算
+- **量化** (`vector/quant.nim`): 标量、乘积和二进制量化
+
+### 图引擎 (`graph/`)
+- **邻接表** (`graph/engine.nim`): 带边权重的有向图
+- **算法** (`graph/engine.nim`): BFS、DFS、Dijkstra、PageRank
+- **社区检测** (`graph/community.nim`): Louvain 算法
+- **模式匹配** (`graph/community.nim`): 子图同构
+- **Cypher 解析器** (`graph/cypher.nim`): 类似 Cypher 的图查询
+
+### 全文搜索 (`fts/`)
+- **倒排索引** (`fts/engine.nim`): 词-文档索引
+- **排名** (`fts/engine.nim`): BM25 和 TF-IDF 评分
+- **模糊搜索** (`fts/engine.nim`): 基于 Levenshtein 距离的匹配
+- **多语言** (`fts/multilang.nim`): EN、BG、DE、FR、RU 的分词器
+
+### 列式引擎 (`core/columnar.nim`)
+- 用于分析查询的按列存储
+- RLE 和字典编码
+- SIMD 加速的聚合操作
+
+## 第4层: 存储
+
+- **LSM-Tree** (`storage/lsm.nim`): MemTable、WAL、SSTable、Bloom Filter、压缩
+- **页面缓存** (`storage/compaction.nim`): LRU 缓存，支持命中率追踪
+- **内存映射 I/O** (`storage/mmap.nim`): 基于 mmap 的文件访问
+- **恢复** (`storage/recovery.nim`): WAL 重放和崩溃恢复
+
+### 写路径
+
+```
+客户端 → 协议 → 认证 → 解析 → AST → IR → 代码生成
+  → StorageOp → MVCC Txn → WAL 写入 → MemTable → 提交
+```
+
+### 读路径
+
+```
+客户端 → 协议 → 认证 → 解析 → AST → IR → 代码生成
+  → StorageOp → MVCC 快照 → MemTable → SSTable → 结果
+```
+
+## 第5层: 分布式
+
+- **Raft 共识** (`core/raft.nim`): 领导者选举、日志复制
+- **分片** (`core/sharding.nim`): 哈希、范围和一致性哈希
+- **复制** (`core/replication.nim`): 同步、异步、半同步模式
+- **Gossip 协议** (`core/gossip.nim`): SWIM 风格的成员管理
+- **分布式事务** (`core/disttxn.nim`): 两阶段提交
+
+## 关键设计决策
+
+1. **纯 Nim**: 无 Cython、Python 或 Rust 依赖
+2. **统一存储**: 一个引擎处理 KV、图、向量、FTS 和列式存储
+3. **嵌入式模式**: 可作为库或服务器运行
+4. **二进制协议**: 自定义高效有线协议
+5. **MVCC**: 多版本并发控制
+6. **模式优先**: 带继承的强类型模式系统
+7. **跨模态**: 跨所有数据模型的单一查询语言
+8. **形式化验证**: 核心分布式算法使用 TLA+ 规范并用 TLC 模型检查
+
+## 模块统计
+
+| 类别 | 模块数 | 代码行数 | 用途 |
+|------|--------|----------|------|
+| Core | 16 | ~4,200 | 服务器、协议、事务、分布式 |
+| Storage | 7 | ~3,100 | LSM、B-Tree、WAL、bloom、压缩、mmap |
+| Query | 7 | ~2,800 | 词法分析、解析、AST、IR、优化器、代码生成、执行器 |
+| Vector | 3 | ~1,200 | HNSW、IVF-PQ、量化、SIMD |
+| Graph | 3 | ~1,000 | 邻接表、算法、社区检测 |
+| FTS | 2 | ~900 | 倒排索引、BM25、模糊搜索、多语言 |
+| Protocol | 7 | ~2,400 | Wire、HTTP、WebSocket、连接池、认证、限流、SSL |
+| Schema | 1 | ~600 | 类型、链接、继承、迁移 |
+| Client | 2 | ~800 | Nim 二进制客户端、文件助手 |
+| CLI | 1 | ~400 | 交互式 BaraQL shell |
+| **总计** | **49** | **~14,100** | |
+
+## 数据流图
+
+### 简单查询
+
+```
+┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
+│ Client │───→│ Lexer  │───→│ Parser │───→│  IR    │───→│ Codegen│
+└────────┘    └────────┘    └────────┘    └────────┘    └───┬────┘
+                                                             │
+┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐       │
+│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘
+└────────┘    └────────┘    └────────┘    └────────┘
+```
+
+### 跨模态查询
+
+```
+                     ┌─────────────┐
+                     │   Parser    │
+                     └──────┬──────┘
+                            │
+                     ┌──────▼──────┐
+                     │   Adaptive  │
+                     │   Optimizer │
+                     └──────┬──────┘
+                            │
+            ┌───────────────┼───────────────┐
+            │               │               │
+     ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
+     │    Vector   │ │    Graph    │ │     FTS     │
+     │    Engine   │ │    Engine   │ │   Engine    │
+     └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
+            │               │               │
+            └───────────────┼───────────────┘
+                            │
+                     ┌──────▼──────┐
+                     │    Join     │
+                     │   & Sort    │
+                     └──────┬──────┘
+                            │
+                     ┌──────▼──────┐
+                     │    Result   │
+                     └─────────────┘
+```
@@ -0,0 +1,82 @@
+# 备份与恢复
+
+## 在线快照
+
+BaraDB 支持在线快照，无需停止服务器。快照使用 MVCC 捕获一致的时间点视图。
+
+### 创建快照
+
+```nim
+import barabadb/core/backup
+
+var bm = newBackupManager()
+bm.createSnapshot("/backup/baradb_2025-01-15")
+```
+
+### 通过 CLI
+
+```bash
+./build/baradadb --snapshot --output=/backup/snapshot.db
+```
+
+### 通过 HTTP API
+
+```bash
+curl -X POST http://localhost:9470/api/backup \
+  -d '{"destination": "/backup/snapshot.db"}'
+```
+
+### 自动备份
+
+```bash
+0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db
+find /backup -name "baradb_*.db" -mtime +7 -delete
+```
+
+## 时间点恢复 (PITR)
+
+### 从快照 + WAL 恢复
+
+```bash
+./build/baradadb --recover \
+  --checkpoint=/backup/snapshot.db \
+  --wal-dir=/backup/wal
+```
+
+### 通过 SQL 恢复
+
+```sql
+RECOVER TO TIMESTAMP '2026-05-07T12:00:00';
+```
+
+## 灾难恢复场景
+
+### 场景 1：文件损坏
+
+```bash
+cp /backup/sstables/000012.sst ./data/sstables/
+./build/baradadb --rebuild-index
+```
+
+### 场景 2：完全数据丢失
+
+```bash
+cp /backup/snapshot.db ./data/
+./build/baradadb --recover --wal-dir=/backup/wal
+```
+
+### 场景 3：集群节点故障
+
+```bash
+BARADB_RAFT_NODE_ID=newnode \
+BARADB_RAFT_PEERS=node1:9001,node2:9001 \
+./build/baradadb
+```
+
+## 最佳实践
+
+1. 定期测试恢复
+2. 将备份存储在场外
+3. 加密备份
+4. 监控备份作业
+5. 记录 RTO/RPO
@@ -0,0 +1,492 @@
+# BaraQL - 查询语言参考
+
+BaraQL 是一个与 SQL 兼容的查询语言，包含图、向量和文档操作的扩展。
+
+## 数据类型
+
+| 类型 | 描述 | 示例 |
+|------|------|------|
+| `null` | 空值 | `null` |
+| `bool` | 布尔值 | `true`, `false` |
+| `int8` | 8 位有符号整数 | `127` |
+| `int16` | 16 位有符号整数 | `32767` |
+| `int32` | 32 位有符号整数 | `2147483647` |
+| `int64` | 64 位有符号整数 | `9223372036854775807` |
+| `float32` | 32 位浮点数 | `3.14` |
+| `float64` | 64 位浮点数 | `3.14159265359` |
+| `str` | UTF-8 字符串 | `'hello'` |
+| `bytes` | 原始字节 | `0xDEADBEEF` |
+| `array<T>` | 同构数组 | `[1, 2, 3]` |
+| `vector` | Float32 向量 | `[0.1, 0.2, 0.3]` |
+| `object` | 键值对象 | `{"a": 1}` |
+| `datetime` | ISO 8601 时间戳 | `'2025-01-15T10:30:00Z'` |
+| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` |
+| `json` | JSON 文档 | `{"key": "value"}` |
+| `jsonb` | 二进制 JSON（已验证） | `{"key": "value"}` |
+
+## 基本查询
+
+### SELECT
+
+```sql
+-- 所有列
+SELECT * FROM users;
+
+-- 特定列
+SELECT name, age FROM users;
+
+-- 别名
+SELECT name AS full_name, age AS years FROM users;
+
+-- DISTINCT
+SELECT DISTINCT department FROM employees;
+
+-- LIMIT 和 OFFSET
+SELECT * FROM users LIMIT 10 OFFSET 20;
+```
+
+### WHERE
+
+```sql
+-- 比较运算符
+SELECT * FROM users WHERE age > 18;
+SELECT * FROM users WHERE age >= 18 AND age <= 65;
+SELECT * FROM users WHERE name = 'Alice';
+SELECT * FROM users WHERE name != 'Bob';
+
+-- 范围
+SELECT * FROM users WHERE age BETWEEN 18 AND 65;
+
+-- 集合成员
+SELECT * FROM users WHERE department IN ('Engineering', 'Sales');
+
+-- 模式匹配
+SELECT * FROM users WHERE name LIKE 'A%';
+SELECT * FROM users WHERE name ILIKE 'alice';  -- 不区分大小写
+
+-- NULL 检查
+SELECT * FROM users WHERE email IS NOT NULL;
+
+-- 逻辑运算符
+SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales');
+```
+
+### ORDER BY
+
+```sql
+-- 升序（默认）
+SELECT * FROM users ORDER BY age;
+
+-- 降序
+SELECT * FROM users ORDER BY age DESC;
+
+-- 多列
+SELECT * FROM users ORDER BY department ASC, age DESC;
+```
+
+### INSERT
+
+```sql
+-- 单行
+INSERT users { name := 'Alice', age := 30 };
+
+-- 显式类型
+INSERT User { name := 'Alice', age := 30 };
+
+-- 多行
+INSERT users {
+  { name := 'Alice', age := 30 },
+  { name := 'Bob', age := 25 }
+};
+```
+
+### UPDATE
+
+```sql
+-- 更新所有行
+UPDATE users SET status = 'active';
+
+-- 条件更新
+UPDATE users SET age = 31 WHERE name = 'Alice';
+
+-- 更新多列
+UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice';
+```
+
+### DELETE
+
+```sql
+-- 删除所有行
+DELETE FROM users;
+
+-- 条件删除
+DELETE FROM users WHERE age < 18;
+```
+
+## 聚合和分组
+
+### 聚合函数
+
+| 函数 | 描述 |
+|------|------|
+| `count(*)` | 计算所有行 |
+| `count(column)` | 计算非 NULL 值 |
+| `sum(column)` | 值之和 |
+| `avg(column)` | 平均值 |
+| `min(column)` | 最小值 |
+| `max(column)` | 最大值 |
+| `stddev(column)` | 标准差 |
+| `variance(column)` | 方差 |
+
+### GROUP BY
+
+```sql
+SELECT department, count(*) as emp_count, avg(salary) as avg_salary
+FROM employees
+GROUP BY department;
+
+-- 带 HAVING
+SELECT department, count(*) as emp_count
+FROM employees
+GROUP BY department
+HAVING count(*) > 5;
+
+-- 多重分组
+SELECT department, role, count(*), avg(salary)
+FROM employees
+GROUP BY department, role;
+```
+
+## JOIN
+
+```sql
+-- INNER JOIN
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+
+-- LEFT JOIN
+SELECT u.name, o.total
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id;
+
+-- RIGHT JOIN
+SELECT u.name, o.total
+FROM users u
+RIGHT JOIN orders o ON u.id = o.user_id;
+
+-- FULL JOIN
+SELECT u.name, o.total
+FROM users u
+FULL JOIN orders o ON u.id = o.user_id;
+
+-- CROSS JOIN
+SELECT u.name, p.name
+FROM users u
+CROSS JOIN products p;
+
+-- 多重 JOIN
+SELECT u.name, o.id, p.name
+FROM orders o
+JOIN users u ON o.user_id = u.id
+JOIN products p ON o.product_id = p.id;
+
+-- Self JOIN
+SELECT e.name, m.name as manager
+FROM employees e
+JOIN employees m ON e.manager_id = m.id;
+```
+
+## CTE（公用表表达式）
+
+```sql
+-- 单个 CTE
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+
+-- 多个 CTE
+WITH
+  recent AS (
+    SELECT * FROM orders WHERE date > '2025-01-01'
+  ),
+  totals AS (
+    SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id
+  )
+SELECT u.name, t.total
+FROM users u
+JOIN totals t ON u.id = t.user_id;
+
+-- 递归 CTE
+WITH RECURSIVE subordinates AS (
+  SELECT id, name, manager_id FROM employees WHERE name = 'CEO'
+  UNION ALL
+  SELECT e.id, e.name, e.manager_id
+  FROM employees e
+  JOIN subordinates s ON e.manager_id = s.id
+)
+SELECT * FROM subordinates;
+```
+
+## 子查询
+
+```sql
+-- SELECT 中的子查询
+SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count
+FROM users u;
+
+-- FROM 中的子查询
+SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active;
+
+-- WHERE 中的子查询 (IN)
+SELECT name FROM users WHERE id IN (SELECT user_id FROM orders);
+
+-- WHERE 中的子查询 (EXISTS)
+SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id);
+
+-- 相关子查询
+SELECT name FROM users u
+WHERE age > (SELECT avg(age) FROM users WHERE department = u.department);
+```
+
+## CASE 表达式
+
+```sql
+SELECT name,
+  CASE
+    WHEN age < 13 THEN 'child'
+    WHEN age < 20 THEN 'teenager'
+    WHEN age < 65 THEN 'adult'
+    ELSE 'senior'
+  END AS category
+FROM users;
+
+-- 简单 CASE
+SELECT name,
+  CASE department
+    WHEN 'Engineering' THEN 'Tech'
+    WHEN 'Sales' THEN 'Revenue'
+    ELSE 'Other'
+  END AS division
+FROM employees;
+```
+
+## 集合运算
+
+```sql
+-- UNION（去重）
+SELECT name FROM customers
+UNION
+SELECT name FROM suppliers;
+
+-- UNION ALL（保留重复）
+SELECT name FROM customers
+UNION ALL
+SELECT name FROM suppliers;
+
+-- INTERSECT
+SELECT name FROM customers
+INTERSECT
+SELECT name FROM suppliers;
+
+-- EXCEPT
+SELECT name FROM customers
+EXCEPT
+SELECT name FROM suppliers;
+```
+
+## 模式定义
+
+### CREATE TYPE
+
+```sql
+CREATE TYPE Person {
+  name: str,
+  age: int32
+};
+
+-- 带必填字段
+CREATE TYPE User {
+  email: str REQUIRED,
+  name: str,
+  age: int32,
+  created_at: datetime DEFAULT now()
+};
+
+-- 带链接
+CREATE TYPE Movie {
+  title: str,
+  year: int32,
+  director: Person
+};
+
+-- 带计算属性
+CREATE TYPE Employee {
+  name: str,
+  base_salary: float64,
+  bonus: float64,
+  total_compensation: float64 COMPUTED (base_salary + bonus)
+};
+```
+
+### 继承
+
+```sql
+CREATE TYPE Animal {
+  name: str
+};
+
+CREATE TYPE Dog EXTENDING Animal {
+  breed: str
+};
+
+CREATE TYPE Cat EXTENDING Animal {
+  indoor: bool
+};
+```
+
+### 索引
+
+```sql
+CREATE INDEX idx_users_name ON users(name);
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_age ON users(age) USING btree;
+```
+
+### DROP
+
+```sql
+DROP TYPE User;
+DROP INDEX idx_users_name;
+```
+
+## 向量搜索
+
+```sql
+-- 插入向量
+INSERT articles {
+  title := 'Nim Programming',
+  embedding := [0.1, 0.2, 0.3, 0.4]
+};
+
+-- 相似性搜索（余弦距离）
+SELECT title FROM articles
+ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
+LIMIT 5;
+
+-- 欧几里得距离
+SELECT title FROM articles
+ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4])
+LIMIT 5;
+
+-- 点积
+SELECT title FROM articles
+ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC
+LIMIT 5;
+
+-- 带元数据过滤
+SELECT title FROM articles
+WHERE category = 'tech'
+ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4])
+LIMIT 5;
+```
+
+## 图模式
+
+```sql
+-- 查找 Alice 的朋友
+MATCH (p:Person)-[:KNOWS]->(friend:Person)
+WHERE p.name = 'Alice'
+RETURN friend.name;
+
+-- 查找最短路径
+MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person))
+WHERE a.name = 'Alice' AND b.name = 'Bob'
+RETURN path;
+
+-- 查找所有关系
+MATCH (p:Person)-[r]->(other)
+WHERE p.name = 'Alice'
+RETURN type(r), other.name;
+
+-- 多跳
+MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person)
+WHERE a.name = 'Alice'
+RETURN c.name;
+
+-- 带聚合
+MATCH (p:Person)-[:KNOWS]->(friend)
+RETURN p.name, count(friend) as friend_count
+ORDER BY friend_count DESC;
+```
+
+## 全文搜索
+
+```sql
+-- 基本搜索
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('database programming');
+
+-- 带相关性评分
+SELECT title, relevance()
+FROM articles
+WHERE MATCH(title, body) AGAINST('Nim language')
+ORDER BY relevance() DESC;
+
+-- 布尔模式
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE);
+
+-- 模糊搜索
+SELECT * FROM articles
+WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
+```
+
+## 事务
+
+```sql
+BEGIN;
+INSERT users { name := 'Alice', age := 30 };
+INSERT orders { user_id := last_insert_id(), total := 100 };
+COMMIT;
+
+-- 带保存点
+BEGIN;
+INSERT users { name := 'Bob', age := 25 };
+SAVEPOINT sp1;
+INSERT orders { user_id := last_insert_id(), total := 200 };
+-- 哎呀，回滚到保存点
+ROLLBACK TO sp1;
+COMMIT;
+```
+
+## 用户定义函数
+
+```sql
+-- 注册 UDF
+CREATE FUNCTION greet(name str) -> str {
+  RETURN 'Hello, ' || name || '!';
+};
+
+-- 使用
+SELECT greet(name) FROM users;
+
+-- 内置函数
+SELECT abs(-5), sqrt(16), lower('HELLO'), len('test');
+```
+
+## 查询提示
+
+```sql
+-- 强制使用索引
+SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18;
+
+-- 强制近似向量搜索
+SELECT /*+ APPROXIMATE */ * FROM vectors
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+
+-- 并行执行
+SELECT /*+ PARALLEL(4) */ * FROM large_table;
+```
@@ -0,0 +1,26 @@
+# B-Tree 索引
+
+用于高效范围扫描和点查询的有序索引结构。
+
+## 用法
+
+```nim
+import barabadb/storage/btree
+
+var btree = newBTreeIndex[string, string]()
+
+btree.insert("key1", "value1")
+btree.insert("key2", "value2")
+
+let values = btree.get("key1")
+let range = btree.scan("key_a", "key_z")
+btree.delete("key1")
+```
+
+## 特性
+
+- 有序键值存储
+- 范围查询（BETWEEN, >, <, >=, <=）
+- 前缀扫描
+- 可配置的页面大小
+- 迭代器支持
@@ -0,0 +1,76 @@
+# 更新日志
+
+## [0.1.0] — 2025-01-15
+
+### 新增功能
+
+- **核心存储引擎**
+  - LSM-Tree 包含 MemTable、WAL、SSTables 和 size-tiered compaction
+  - B-Tree 有序索引支持范围扫描和 MVCC copy-on-write
+  - Bloom 过滤器优化 SSTable 跳过
+  - Memory-mapped I/O
+  - LRU 页面缓存
+
+- **查询引擎 (BaraQL)**
+  - SQL 兼容的词法分析器，80+ 种标记类型
+  - 递归下降解析器，生成 25+ 种节点类型的 AST
+  - 中间表示（IR）
+  - 自适应查询优化器，支持跨模态规划
+  - 并行查询执行器
+
+- **BaraQL 语言功能**
+  - SELECT、INSERT、UPDATE、DELETE
+  - WHERE、ORDER BY、LIMIT、OFFSET
+  - GROUP BY、HAVING、聚合函数
+  - INNER JOIN、LEFT JOIN、RIGHT JOIN、FULL JOIN、CROSS JOIN
+  - CTEs (WITH)
+  - 子查询
+  - CASE 表达式
+  - UNION、INTERSECT、EXCEPT
+
+- **向量引擎**
+  - HNSW 近似最近邻搜索
+  - IVF-PQ 大规模向量搜索
+  - SIMD 优化的距离函数
+  - 量化：标量 8-bit/4-bit、乘积量化、二进制
+
+- **图引擎**
+  - 邻接表存储
+  - BFS 和 DFS 遍历
+  - Dijkstra 最短路径
+  - PageRank
+  - Louvain 社区检测
+  - Cypher 查询解析器
+
+- **全文搜索**
+  - 倒排索引
+  - BM25 排名
+  - TF-IDF
+  - 模糊搜索
+  - 多语言分词器
+
+- **协议**
+  - Binary wire protocol
+  - HTTP/REST JSON API
+  - WebSocket
+  - Connection pooling
+  - JWT 认证
+  - TLS/SSL
+
+- **分布式系统**
+  - Raft 共识
+  - Hash、range、consistent-hash 分片
+  - 同步/异步/半同步复制
+  - Gossip 协议
+  - 两阶段提交
+
+### 性能
+
+- LSM-Tree: 580K 写入/秒，720K 读取/秒
+- B-Tree: 1.2M 插入/秒，1.5M 查找/秒
+- Vector SIMD: 850K 余弦距离/秒（dim=768）
+
+### 测试
+
+- 56 个测试套件中的 262 个测试
+- 100% 通过率
@@ -0,0 +1,66 @@
+# 客户端 SDK
+
+BaraDB 为 JavaScript/TypeScript、Python、Nim 和 Rust 提供官方客户端库。
+
+## JavaScript / TypeScript
+
+### 安装
+
+```bash
+npm install baradb
+```
+
+### 基本用法
+
+```typescript
+import { Client } from 'baradb';
+
+const client = new Client('localhost', 9472);
+await client.connect();
+
+const result = await client.query('SELECT name, age FROM users WHERE age > 18');
+```
+
+## Python
+
+### 安装
+
+```bash
+pip install baradb
+```
+
+### 基本用法
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472)
+client.connect()
+result = client.query("SELECT name, age FROM users WHERE age > 18")
+```
+
+## Nim（嵌入式模式）
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key", cast[seq[byte]]("value"))
+let (found, val) = db.get("key")
+db.close()
+```
+
+## Rust
+
+```rust
+use baradb::Client;
+
+let mut client = Client::connect("localhost:9472").await?;
+```
+
+## HTTP/REST
+
+```bash
+curl -X POST http://localhost:9470/api/query \
+  -d '{"query": "SELECT * FROM users"}'
+```
@@ -0,0 +1,50 @@
+# 列式存储
+
+用于分析查询和聚合的面向列的存储。
+
+## 用法
+
+```nim
+import barabadb/core/columnar
+
+var batch = newColumnBatch()
+var ageCol = batch.addInt64Col("age")
+var nameCol = batch.addStringCol("name")
+
+ageCol.appendInt64(25)
+nameCol.appendString("Alice")
+```
+
+## 聚合
+
+```nim
+echo ageCol.sumInt64()
+echo ageCol.avgInt64()
+echo ageCol.minInt64()
+echo ageCol.maxInt64()
+```
+
+## 编码
+
+### RLE
+
+```nim
+let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3])
+```
+
+### Dictionary
+
+```nim
+let dict = dictEncode(@["apple", "banana", "apple"])
+```
+
+## 列类型
+
+| 类型 | 描述 |
+|------|------|
+| `int32` | 32 位整数 |
+| `int64` | 64 位整数 |
+| `float32` | 32 位浮点数 |
+| `float64` | 64 位浮点数 |
+| `string` | 可变长度字符串 |
+| `bool` | 布尔值 |
@@ -0,0 +1,217 @@
+# BaraDB - 配置参考
+
+BaraDB 可以通过**环境变量**、**配置文件**或**命令行标志**进行配置。
+
+## 优先级顺序
+
+1. 命令行标志（最高优先级）
+2. 环境变量
+3. 配置文件 (`baradb.conf` 或 `baradb.json`)
+4. 内置默认值（最低优先级）
+
+## 环境变量
+
+### 网络
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_ADDRESS` | `127.0.0.1` | 绑定地址 |
+| `BARADB_PORT` | `9472` | TCP 二进制协议端口 |
+| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API 端口 |
+| `BARADB_WS_PORT` | `9471` | WebSocket 端口 |
+
+### 存储
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_DATA_DIR` | `./data` | 数据目录路径 |
+| `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable 大小（MB） |
+| `BARADB_CACHE_SIZE_MB` | `256` | 页面缓存大小（MB） |
+| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | WAL fsync 间隔（0 = 每次写入） |
+| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | 后台压缩间隔 |
+| `BARADB_BLOOM_BITS_PER_KEY` | `10` | 每个键的 Bloom 过滤器位数 |
+
+### TLS/SSL
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_TLS_ENABLED` | `false` | 启用 TLS |
+| `BARADB_CERT_FILE` | — | TLS 证书路径 |
+| `BARADB_KEY_FILE` | — | TLS 私钥路径 |
+
+### 安全
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_AUTH_ENABLED` | `false` | 启用认证 |
+| `BARADB_JWT_SECRET` | — | JWT 签名密钥 |
+| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | 全局请求数/秒 |
+| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | 每客户端请求数/秒 |
+
+### 日志
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_LOG_LEVEL` | `info` | 日志级别：debug, info, warn, error |
+| `BARADB_LOG_FILE` | — | 日志文件路径（空则输出到 stdout） |
+| `BARADB_LOG_FORMAT` | `json` | 日志格式：json, text |
+
+### 向量引擎
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_VECTOR_M` | `16` | HNSW `M` 参数 |
+| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` |
+| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` |
+
+### 图引擎
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | PageRank 迭代次数 |
+| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank 阻尼因子 |
+| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain 分辨率参数 |
+
+### 分布式
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_RAFT_NODE_ID` | — | 集群中的唯一节点 ID |
+| `BARADB_RAFT_PEERS` | — | 逗号分隔的节点地址列表 |
+| `BARADB_RAFT_PORT` | `9001` | Raft 内部通信端口 |
+| `BARADB_SHARD_COUNT` | `1` | 分片数量 |
+| `BARADB_REPLICATION_FACTOR` | `1` | 复制因子 |
+
+## 配置文件
+
+### baradb.conf (INI 风格)
+
+```ini
+[server]
+address = "0.0.0.0"
+port = 9472
+http_port = 9470
+ws_port = 9471
+
+[storage]
+data_dir = "/var/lib/baradb"
+memtable_size_mb = 256
+cache_size_mb = 512
+wal_sync_interval_ms = 10
+compaction_interval_ms = 30000
+
+[tls]
+enabled = true
+cert_file = "/etc/baradb/server.crt"
+key_file = "/etc/baradb/server.key"
+
+[auth]
+enabled = true
+jwt_secret = "change-me-in-production"
+rate_limit_global = 10000
+rate_limit_per_client = 1000
+
+[logging]
+level = "info"
+format = "json"
+file = "/var/log/baradb/baradb.log"
+
+[vector]
+m = 16
+ef_construction = 200
+ef_search = 64
+
+[cluster]
+raft_node_id = "node1"
+raft_peers = "node2:9001,node3:9001"
+```
+
+### baradb.json
+
+```json
+{
+  "server": {
+    "address": "0.0.0.0",
+    "port": 9472,
+    "http_port": 9470,
+    "ws_port": 9471
+  },
+  "storage": {
+    "data_dir": "/var/lib/baradb",
+    "memtable_size_mb": 256,
+    "cache_size_mb": 512
+  },
+  "tls": {
+    "enabled": true,
+    "cert_file": "/etc/baradb/server.crt",
+    "key_file": "/etc/baradb/server.key"
+  }
+}
+```
+
+## 命令行标志
+
+```bash
+./build/baradadb --help
+```
+
+```
+BaraDB v0.1.0 — Multimodal Database Engine
+
+Usage:
+  baradadb [options]
+
+Options:
+  -c, --config <file>       配置文件路径
+  -p, --port <port>         TCP 二进制端口（默认：9472）
+  --http-port <port>        HTTP 端口（默认：9470）
+  --ws-port <port>         WebSocket 端口（默认：9471）
+  -d, --data-dir <dir>      数据目录（默认：./data）
+  --tls-cert <file>         TLS 证书文件
+  --tls-key <file>          TLS 私钥文件
+  --log-level <level>       日志级别：debug, info, warn, error
+  --log-file <file>         日志文件路径
+  --shell                   启动交互式 shell
+  --version                 显示版本
+  --recover                 运行 WAL 恢复
+  --checkpoint <file>      用于恢复的检查点
+  -h, --help                显示此帮助信息
+```
+
+## 配置示例
+
+### 开发环境
+
+```bash
+./build/baradadb \
+  --log-level debug \
+  --data-dir ./dev_data
+```
+
+### 生产环境单节点
+
+```bash
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+BARADB_LOG_LEVEL=warn \
+BARADB_LOG_FILE=/var/log/baradb/baradb.log \
+BARADB_MEMTABLE_SIZE_MB=256 \
+BARADB_CACHE_SIZE_MB=1024 \
+./build/baradadb
+```
+
+### 生产环境集群（3 节点）
+
+```bash
+# 节点 1
+BARADB_ADDRESS=0.0.0.0 \
+BARADB_PORT=9472 \
+BARADB_RAFT_NODE_ID=node1 \
+BARADB_RAFT_PEERS=node2:9001,node3:9001 \
+BARADB_SHARD_COUNT=4 \
+BARADB_REPLICATION_FACTOR=2 \
+./build/baradadb
+```
@@ -0,0 +1,48 @@
+# 跨模态查询
+
+BaraDB 的独特能力是执行跨越多个存储引擎的查询，使用单一的 BaraQL 语句。
+
+## 概述
+
+- **文档/KV** (LSM-Tree) — 结构化记录
+- **图** (邻接表) — 关系
+- **向量** (HNSW/IVF-PQ) — 相似性搜索
+- **全文** (倒排索引) — 文本搜索
+- **列式** — 分析聚合
+
+## 查询模式
+
+### 向量 + 全文
+
+```sql
+SELECT title FROM articles
+WHERE MATCH(body) AGAINST('machine learning')
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+```
+
+### 图 + 向量
+
+```sql
+MATCH (u:User)-[:KNOWS]->(friend:User)
+WHERE u.name = 'Alice'
+ORDER BY cosine_distance(friend.taste_vector, u.taste_vector)
+RETURN friend.name;
+```
+
+## 优化
+
+### 跨模态查询规划器
+
+1. 最具选择性的过滤器优先
+2. 将谓词下推到每个引擎
+3. 使用 Bloom 过滤器进行 KV 查找
+4. 并行化独立分支
+
+## 性能
+
+| 查询类型 | 延迟（10K 行） |
+|----------|-----------------|
+| FTS + Vector | 15 ms |
+| Graph + Vector | 25 ms |
+| FTS + Aggregate | 12 ms |
@@ -0,0 +1,249 @@
+# BaraDB - 部署指南
+
+## Docker
+
+完整的 Docker 部署指南请参见 [Docker 指南](docker.md)。
+
+### 快速开始
+
+```bash
+docker build -t baradb:latest .
+docker compose up -d
+```
+
+### Docker Compose 文件
+
+| 文件 | 用途 |
+|------|------|
+| `docker-compose.yml` | 开发环境 |
+| `docker-compose.prod.yml` | 生产环境 |
+| `docker-compose.override.yml` | 开发覆盖（自动） |
+
+### 生产环境
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Docker Swarm
+
+```bash
+docker stack deploy -c docker-compose.prod.yml baradb
+```
+
+## systemd 服务
+
+创建 `/etc/systemd/system/baradb.service`:
+
+```ini
+[Unit]
+Description=BaraDB Multimodal Database
+After=network.target
+
+[Service]
+Type=simple
+User=baradb
+Group=baradb
+WorkingDirectory=/var/lib/baradb
+ExecStart=/usr/local/bin/baradadb
+Restart=always
+RestartSec=5
+
+Environment=BARADB_PORT=9472
+Environment=BARADB_HTTP_PORT=9470
+Environment=BARADB_DATA_DIR=/var/lib/baradb/data
+Environment=BARADB_LOG_LEVEL=info
+
+# 安全加固
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/baradb/data
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启用并启动:
+
+```bash
+sudo useradd -r -s /bin/false baradb
+sudo mkdir -p /var/lib/baradb/data
+sudo chown -R baradb:baradb /var/lib/baradb
+sudo cp build/baradadb /usr/local/bin/
+sudo systemctl daemon-reload
+sudo systemctl enable --now baradb
+```
+
+## Kubernetes
+
+### StatefulSet
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: baradb
+spec:
+  serviceName: baradb
+  replicas: 3
+  selector:
+    matchLabels:
+      app: baradb
+  template:
+    metadata:
+      labels:
+        app: baradb
+    spec:
+      containers:
+      - name: baradb
+        image: baradb:latest
+        ports:
+        - containerPort: 9472
+          name: binary
+        - containerPort: 9470
+          name: http
+        - containerPort: 9471
+          name: websocket
+        env:
+        - name: BARADB_DATA_DIR
+          value: /data
+        - name: BARADB_RAFT_NODE_ID
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
+        volumeMounts:
+        - name: data
+          mountPath: /data
+  volumeClaimTemplates:
+  - metadata:
+      name: data
+    spec:
+      accessModes: ["ReadWriteOnce"]
+      resources:
+        requests:
+          storage: 100Gi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: baradb
+spec:
+  selector:
+    app: baradb
+  ports:
+  - port: 9472
+    name: binary
+  - port: 9470
+    name: http
+  - port: 9471
+    name: websocket
+  clusterIP: None
+```
+
+## 反向代理 (nginx)
+
+```nginx
+upstream baradb_http {
+    server 127.0.0.1:9470;
+}
+
+upstream baradb_ws {
+    server 127.0.0.1:9471;
+}
+
+server {
+    listen 80;
+    server_name db.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name db.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem;
+
+    location /api/ {
+        proxy_pass http://baradb_http/;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /ws/ {
+        proxy_pass http://baradb_ws/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+## 高可用性
+
+### 3 节点 Raft 集群
+
+```bash
+# 节点 1
+BARADB_RAFT_NODE_ID=node1 \
+BARADB_RAFT_PEERS=node2:9001,node3:9001 \
+./build/baradadb
+
+# 节点 2
+BARADB_RAFT_NODE_ID=node2 \
+BARADB_RAFT_PEERS=node1:9001,node3:9001 \
+./build/baradadb
+
+# 节点 3
+BARADB_RAFT_NODE_ID=node3 \
+BARADB_RAFT_PEERS=node1:9001,node2:9001 \
+./build/baradadb
+```
+
+## 云部署
+
+### AWS EC2
+
+推荐实例: `m6i.2xlarge` (8 vCPU, 32 GB RAM)
+
+```bash
+# User data script
+#!/bin/bash
+apt-get update
+apt-get install -y nim
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
+chmod +x baradadb-linux-amd64
+mv baradadb-linux-amd64 /usr/local/bin/baradadb
+
+mkdir -p /data/baradb
+cat > /etc/systemd/system/baradb.service << 'EOF'
+[Unit]
+Description=BaraDB
+After=network.target
+[Service]
+ExecStart=/usr/local/bin/baradadb
+Environment=BARADB_DATA_DIR=/data/baradb
+Restart=always
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now baradb
+```
+
+### GCP Cloud Run（仅 HTTP）
+
+```bash
+gcloud run deploy baradb \
+  --image gcr.io/PROJECT/baradb \
+  --port 9470 \
+  --memory 4Gi \
+  --cpu 2 \
+  --max-instances 10
+```
@@ -0,0 +1,91 @@
+# 分布式系统
+
+BaraDB 支持使用 Raft 共识、分片和复制进行分布式部署。
+
+## Raft 共识
+
+领导者选举和日志复制：
+
+```nim
+import barabadb/core/raft
+
+var cluster = newRaftCluster()
+cluster.addNode("node1")
+cluster.addNode("node2")
+cluster.addNode("node3")
+
+let n1 = cluster.nodes["n1"]
+n1.becomeCandidate()
+n1.becomeLeader()
+```
+
+## 分片
+
+跨节点分发数据：
+
+```nim
+import barabadb/core/sharding
+
+var router = newShardRouter(ShardConfig(
+  numShards: 4,
+  replicas: 2,
+  strategy: ssHash
+))
+router.rebalance(@["node1", "node2", "node3"])
+```
+
+### 分片策略
+
+| 策略 | 描述 |
+|------|------|
+| `ssHash` | 基于哈希的分片 |
+| `ssRange` | 基于范围的分片 |
+| `ssConsistent` | 一致性哈希 |
+
+## 复制
+
+```nim
+import barabadb/core/replication
+
+var rm = newReplicationManager(rmSync)
+rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
+```
+
+### 复制模式
+
+| 模式 | 描述 |
+|------|------|
+| `rmSync` | 同步复制 |
+| `rmAsync` | 异步复制 |
+| `rmSemiSync` | 半同步复制 |
+
+## Gossip 协议
+
+```nim
+import barabadb/core/gossip
+
+var g = newGossipManager()
+g.addNode("node1")
+g.addNode("node2")
+g.tick()
+```
+
+## 分布式事务
+
+两阶段提交：
+
+```nim
+import barabadb/core/disttxn
+
+var dt = newDistributedTxn()
+dt.prepare(@["node1", "node2"])
+dt.commit()
+```
+
+## 形式化验证
+
+核心分布式算法在 TLA+ 中形式化规范并通过模型检查：
+
+- **Raft Consensus** — `formal-verification/raft.tla`
+- **Two-Phase Commit** — `formal-verification/twopc.tla`
+- **Replication** — `formal-verification/replication.tla`
@@ -0,0 +1,129 @@
+# Docker 部署指南
+
+## 快速开始
+
+```bash
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+
+docker build -t baradb:latest .
+
+docker compose up -d
+
+docker compose ps
+docker compose logs -f
+```
+
+## 文件
+
+| 文件 | 描述 |
+|------|------|
+| `Dockerfile` | 多阶段生产构建 |
+| `docker-compose.yml` | 开发配置 |
+| `docker-compose.prod.yml` | 生产配置 |
+| `docker-compose.override.yml` | 开发覆盖（自动加载）|
+| `docker-entrypoint.sh` | 初始化入口脚本 |
+| `.dockerignore` | 不复制到镜像的文件 |
+| `scripts/docker-build.sh` | 构建辅助脚本 |
+| `scripts/docker-run.sh` | 运行辅助脚本 |
+
+## 构建镜像
+
+```bash
+docker build -t baradb:latest .
+./scripts/docker-build.sh
+```
+
+## 运行
+
+### 开发 (docker compose)
+
+```bash
+docker compose up -d
+docker compose down
+docker compose logs -f
+```
+
+### 生产 (docker compose)
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### 手动 (docker run)
+
+```bash
+docker run -d \
+  --name baradb \
+  -p 9472:9472 \
+  -p 9470:9470 \
+  -p 9471:9471 \
+  -v baradb_data:/data \
+  baradb:latest
+```
+
+## 端口
+
+| 端口 | 描述 |
+|------|------|
+| `9472` | 二进制协议 |
+| `9470` | HTTP/REST API |
+| `9471` | WebSocket |
+
+## 环境变量
+
+| 变量 | 默认值 | 描述 |
+|------|--------|------|
+| `BARADB_ADDRESS` | `0.0.0.0` | 监听地址 |
+| `BARADB_PORT` | `9472` | 二进制协议端口 |
+| `BARADB_HTTP_PORT` | `9470` | HTTP 端口 |
+| `BARADB_DATA_DIR` | `/data` | 数据目录 |
+
+## 卷
+
+| 路径 | 描述 |
+|------|------|
+| `/data` | 主数据目录 |
+| `/data/server/wal` | 预写日志 |
+| `/data/server/sstables` | SSTable 文件 |
+
+## 生产检查清单
+
+- [ ] 在 `./certs/` 创建 TLS 证书
+- [ ] 设置强 `BARADB_JWT_SECRET`
+- [ ] 配置防火墙规则
+- [ ] 配置定期备份
+- [ ] 检查资源限制
+- [ ] 设置监控
+
+## Docker 中的 TLS
+
+```bash
+mkdir -p certs
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout certs/server.key -out certs/server.crt
+```
+
+## Docker 备份
+
+```bash
+docker exec baradb /app/backup backup --data-dir=/data
+docker exec baradb /app/backup list
+docker exec baradb /app/backup restore --input=backup_xxx.tar.gz
+```
+
+## 故障排除
+
+### 容器不启动
+
+```bash
+docker compose logs -f baradb
+docker compose ps
+```
+
+### 无法连接数据库
+
+```bash
+docker port baradb
+docker exec baradb wget -qO- http://localhost:9470/health
+```
@@ -0,0 +1,47 @@
+# 全文搜索引擎
+
+具有 BM25 和 TF-IDF 排名的倒排索引。
+
+## 用法
+
+```nim
+import barabadb/fts/engine
+
+var idx = newInvertedIndex()
+idx.addDocument(1, "Nim is a fast programming language")
+idx.addDocument(2, "Python is popular for data science")
+
+let results = idx.search("programming language")
+let fuzzy = idx.fuzzySearch("programing", maxDistance = 2)
+```
+
+## 排名方法
+
+### BM25
+
+```nim
+let bm25 = idx.searchBM25("query terms")
+```
+
+### TF-IDF
+
+```nim
+let tfidf = idx.searchTfidf("query terms")
+```
+
+## 搜索功能
+
+| 功能 | 描述 |
+|------|------|
+| Fuzzy search | 允许拼写错误（Levenshtein 距离） |
+| Wildcard | 前缀、后缀和中间通配符 |
+| Regex | 正则表达式模式 |
+| Phrase search | 精确短语匹配 |
+| Boolean | AND、OR、NOT 运算符 |
+
+## SQL 接口
+
+```sql
+CREATE INDEX idx_fts ON articles(body) USING FTS;
+SELECT * FROM articles WHERE body @@ 'machine learning';
+```
@@ -0,0 +1,42 @@
+# 图引擎
+
+具有内置算法的邻接表存储，用于图遍历和分析。
+
+## 用法
+
+```nim
+import barabadb/graph/engine
+
+var g = newGraph()
+let alice = g.addNode("Person", {"Name": "Alice"}.toTable)
+let bob = g.addNode("Person", {"Name": "Bob"}.toTable)
+discard g.addEdge(alice, bob, "knows")
+
+let bfs = g.bfs(alice)
+let path = g.shortestPath(alice, bob)
+let ranks = g.pageRank()
+```
+
+## 算法
+
+| 算法 | 描述 |
+|------|------|
+| `bfs` | 广度优先遍历 |
+| `dfs` | 深度优先遍历 |
+| `dijkstra` | 最短加权路径 |
+| `pageRank` | 节点重要性排名 |
+| `louvain` | 社区检测 |
+| `patternMatch` | 子图同构 |
+
+## Cypher 查询
+
+```nim
+import barabadb/graph/cypher
+
+var engine = newCypherEngine(g)
+let results = engine.execute("""
+  MATCH (p:Person)-[:KNOWS]->(friend:Person)
+  WHERE p.name = 'Alice'
+  RETURN friend.name
+""")
+```
@@ -0,0 +1,59 @@
+# BaraDB 文档 (简体中文)
+
+**使用 Nim 编写的多模态数据库引擎 — 100% 原生实现，零依赖。**
+
+## 快速链接
+
+> **注意：** 中文文档正在开发中。请参阅 [英文版](../en/) 获取完整信息。
+
+### 入门指南
+- [安装](../en/installation.md)
+- [快速开始](../en/quickstart.md)
+- [架构概述](../en/architecture.md)
+- [配置参考](../en/configuration.md)
+- [部署指南](../en/deployment.md)
+
+### 核心概念
+- [BaraQL 查询语言](../en/baraql.md)
+- [存储引擎](../en/storage.md)
+- [模式系统](../en/schema.md)
+- [跨模态查询](../en/crossmodal.md)
+
+### 引擎
+- [LSM-Tree 存储](../en/lsm.md)
+- [B-Tree 索引](../en/btree.md)
+- [向量搜索](../en/vector.md)
+- [图引擎](../en/graph.md)
+- [全文搜索](../en/fts.md)
+- [列式存储](../en/columnar.md)
+
+### API 与客户端
+- [客户端 SDK](../en/clients.md)
+- [二进制协议](../en/api-binary.md)
+- [HTTP/REST API](../en/api-http.md)
+- [WebSocket API](../en/api-websocket.md)
+- [协议参考](../en/protocol.md)
+
+### 运维
+- [性能与基准测试](../en/performance.md)
+- [安全指南](../en/security.md)
+- [监控与可观测性](../en/monitoring.md)
+- [备份与恢复](../en/backup.md)
+- [故障排除](../en/troubleshooting.md)
+
+### 高级主题
+- [事务与 MVCC](../en/transactions.md)
+- [分布式系统](../en/distributed.md)
+- [用户定义函数](../en/udf.md)
+
+---
+
+## 项目信息
+
+- [更新日志](../en/changelog.md)
+- [许可证](../../LICENSE)
+- [GitHub 仓库](https://github.com/katehonz/barabaDB)
+
+---
+
+*中文文档正在翻译中。*
@@ -0,0 +1,309 @@
+# BaraDB - 安装指南
+
+## 系统要求
+
+- **Nim 编译器** >= 2.2.0
+- **OpenSSL 开发头文件** (用于 TLS 支持)
+- **操作系统**: Linux、macOS、Windows
+
+### 支持的平台
+
+| 操作系统 | 架构 | 状态 |
+|----------|------|------|
+| Linux | x86_64 | ✅ 完全支持 |
+| Linux | ARM64 | ✅ 完全支持 |
+| macOS | x86_64 | ✅ 完全支持 |
+| macOS | ARM64 (Apple Silicon) | ✅ 完全支持 |
+| Windows | x86_64 | ✅ 支持 |
+| FreeBSD | x86_64 | 🟡 社区测试 |
+
+## 安装 Nim
+
+### Linux
+
+```bash
+# 官方安装脚本
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install nim
+
+# Fedora
+sudo dnf install nim
+
+# Arch Linux
+sudo pacman -S nim
+```
+
+### macOS
+
+```bash
+# Homebrew
+brew install nim
+
+# MacPorts
+sudo port install nim
+```
+
+### Windows
+
+```powershell
+# 使用 choosenim
+curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
+
+# 使用 winget
+winget install nim
+
+# 使用 scoop
+scoop install nim
+```
+
+### 验证安装
+
+```bash
+nim --version
+# 预期输出: Nim Compiler Version 2.2.0 或更高
+```
+
+## 安装 OpenSSL
+
+### Linux
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install libssl-dev
+
+# Fedora
+sudo dnf install openssl-devel
+
+# Arch Linux
+sudo pacman -S openssl
+```
+
+### macOS
+
+OpenSSL 已随系统提供。如有需要:
+
+```bash
+brew install openssl
+```
+
+### Windows
+
+OpenSSL 已捆绑在 Nim Windows 分发版中。如需手动构建，
+请从 [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) 下载。
+
+## 构建 BaraDB
+
+### 克隆仓库
+
+```bash
+git clone https://github.com/katehonz/barabaDB.git
+cd barabaDB
+```
+
+### 安装依赖
+
+```bash
+nimble install -d -y
+```
+
+### 构建选项
+
+#### 调试构建
+
+```bash
+nim c -d:ssl -o:build/baradadb src/baradadb.nim
+```
+
+#### 发布构建 (推荐)
+
+```bash
+nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
+```
+
+#### 使用 Nimble Tasks
+
+```bash
+# 调试构建
+nimble build_debug
+
+# 发布构建
+nimble build_release
+```
+
+#### 精简二进制文件
+
+```bash
+nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
+strip build/baradadb
+```
+
+### 验证构建
+
+```bash
+./build/baradadb --version
+# 预期输出: BaraDB v0.1.0 — Multimodal Database Engine
+```
+
+## 运行测试
+
+### 所有测试
+
+```bash
+nim c -d:ssl -r tests/test_all.nim
+```
+
+### 特定测试套件
+
+```bash
+# 存储测试
+nim c -d:ssl -r tests/test_storage.nim
+
+# 查询引擎测试
+nim c -d:ssl -r tests/test_query.nim
+
+# 协议测试
+nim c -d:ssl -r tests/test_protocol.nim
+```
+
+### 基准测试
+
+```bash
+nim c -d:ssl -d:release -r benchmarks/bench_all.nim
+```
+
+## 安装选项
+
+### 系统级安装
+
+```bash
+# 构建发布版二进制文件
+nimble build_release
+
+# 安装到 /usr/local/bin
+sudo cp build/baradadb /usr/local/bin/
+sudo chmod +x /usr/local/bin/baradadb
+
+# 创建数据目录
+sudo mkdir -p /var/lib/baradb
+sudo chmod 755 /var/lib/baradb
+```
+
+### 预编译二进制文件
+
+为您的平台下载最新的发布版本:
+
+```bash
+# Linux x86_64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
+chmod +x baradadb-linux-amd64
+mv baradadb-linux-amd64 /usr/local/bin/baradadb
+
+# Linux ARM64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64
+chmod +x baradadb-linux-arm64
+mv baradadb-linux-arm64 /usr/local/bin/baradadb
+
+# macOS
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64
+chmod +x baradadb-darwin-amd64
+mv baradadb-darwin-amd64 /usr/local/bin/baradadb
+```
+
+### Docker
+
+```bash
+# 拉取官方镜像
+docker pull barabadb/barabadb:latest
+
+# 运行
+docker run -d \
+  -p 9472:9472 \
+  -p 9470:9470 \
+  -p 9471:9471 \
+  -v baradb_data:/data \
+  barabadb/barabadb
+```
+
+### Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+### 嵌入式使用 (Nim 项目)
+
+添加到您的 `.nimble` 文件:
+
+```nim
+requires "barabadb >= 0.1.0"
+```
+
+在代码中使用:
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key", cast[seq[byte]]("value"))
+let (found, val) = db.get("key")
+db.close()
+```
+
+## 首次运行
+
+```bash
+# 启动服务器
+./build/baradadb
+
+# 预期输出:
+# BaraDB v0.1.0 — Multimodal Database Engine
+# BaraDB TCP listening on 127.0.0.1:9472
+
+# 使用 HTTP API 测试
+curl http://localhost:9470/health
+
+# 交互式 shell
+./build/baradadb --shell
+```
+
+## 安装故障排除
+
+### "cannot open file: hunos"
+
+```bash
+nimble install -d -y
+```
+
+### "BaraDB requires SSL support"
+
+始终使用 `-d:ssl` 编译:
+
+```bash
+nim c -d:ssl -o:build/baradadb src/baradadb.nim
+```
+
+### 编译缓慢
+
+使用并行编译:
+
+```bash
+nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim
+```
+
+### 二进制文件过大
+
+使用大小优化:
+
+```bash
+nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim
+```
+
+## 下一步
+
+- [快速入门指南](quickstart.md)
+- [配置参考](configuration.md)
+- [架构概述](architecture.md)
+- [BaraQL 查询语言](baraql.md)
@@ -0,0 +1,48 @@
+# LSM-Tree 存储引擎
+
+BaraDB 的主要存储引擎，使用 Log-Structured Merge-Tree 架构。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────┐
+│                   Writes                     │
+│         (append to WAL + MemTable)           │
+└─────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────┐
+│                  MemTable                    │
+│         (in-memory sorted buffer)            │
+└─────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────┐
+│                  SSTable                     │
+│          (sorted string table on disk)       │
+└─────────────────────────────────────────────┘
+```
+
+## 用法
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+
+db.put("key1", cast[seq[byte]]("value1"))
+
+let (found, value) = db.get("key1")
+
+db.delete("key1")
+
+db.close()
+```
+
+## 特性
+
+- **写优化**：追加式日志结构
+- **持久性**：WAL 确保崩溃恢复
+- **Bloom Filter**：快速否定查找
+- **压缩**：大小分层策略合并 SSTable
+- **页面缓存**：LRU 缓存常用页面
@@ -0,0 +1,104 @@
+# 监控与可观测性
+
+## 健康检查
+
+### HTTP 健康端点
+
+```bash
+curl http://localhost:9470/health
+```
+
+响应：
+
+```json
+{
+  "status": "healthy",
+  "version": "0.1.0",
+  "uptime_seconds": 86400,
+  "checks": {
+    "storage": "ok",
+    "memory": "ok",
+    "connections": "ok"
+  }
+}
+```
+
+### Readiness Probe
+
+```bash
+curl http://localhost:9470/ready
+```
+
+服务器准备接受流量时返回 `200 OK`，启动期间返回 `503`。
+
+## 指标
+
+### Prometheus 兼容指标
+
+```bash
+curl http://localhost:9470/metrics
+```
+
+示例输出：
+
+```
+baradb_queries_total 152340
+baradb_queries_duration_seconds_bucket{le="0.001"} 45000
+baradb_storage_lsm_size_bytes 2147483648
+baradb_cache_hit_rate 0.94
+baradb_active_connections 42
+```
+
+### JSON 格式指标
+
+```bash
+curl http://localhost:9470/metrics?format=json
+```
+
+## 日志
+
+### 日志级别
+
+| 级别 | 描述 |
+|------|------|
+| `debug` | 详细的内部操作 |
+| `info` | 正常操作 |
+| `warn` | 可恢复的问题 |
+| `error` | 需要关注的故障 |
+
+### 结构化 JSON 日志
+
+```bash
+BARADB_LOG_LEVEL=info \
+BARADB_LOG_FORMAT=json \
+BARADB_LOG_FILE=/var/log/baradb/baradb.log \
+./build/baradadb
+```
+
+## Grafana 仪表板
+
+导入仪表板 ID `baradb-001` 或使用 `monitoring/grafana-dashboard.json` 中的 JSON。
+
+关键面板：
+- 每秒查询数
+- 查询延迟百分位数 (p50, p95, p99)
+- 存储大小和 SSTable 数量
+- 缓存命中率
+- 活跃连接数
+- 事务率
+- 错误率
+
+## 集群监控
+
+```bash
+curl http://node1:9470/metrics/cluster
+```
+
+## 使用指标进行故障排除
+
+| 症状 | 指标 | 操作 |
+|------|------|------|
+| 查询慢 | `baradb_queries_duration_seconds` | 检查缓存命中率，考虑添加索引 |
+| 内存高 | `process_resident_memory_bytes` | 减小 memtable/cache 大小 |
+| 存储增长 | `baradb_storage_lsm_size_bytes` | 运行手动压缩 |
+| 连接错误 | `baradb_active_connections` | 增加连接池或添加节点 |
@@ -0,0 +1,94 @@
+# 性能指南
+
+## 基准测试方法论
+
+所有基准测试使用：
+- **编译器**: Nim 2.2.0 配合 `-d:release --opt:speed`
+- **CPU**: AMD Ryzen 9 5900X (12 cores / 24 threads)
+- **内存**: 64 GB DDR4-3600
+- **存储**: Samsung 980 Pro NVMe SSD
+
+```bash
+nim c -d:ssl -d:release -r benchmarks/bench_all.nim
+```
+
+## 存储引擎基准测试
+
+### LSM-Tree 键值
+
+| 指标 | 值 |
+|------|-----|
+| 写入吞吐量 | ~580,000 ops/s |
+| 读取吞吐量 | ~720,000 ops/s |
+| 平均写入延迟 | 1.7 µs |
+| 平均读取延迟 | 1.4 µs |
+
+### B-Tree 索引
+
+| 指标 | 值 |
+|------|-----|
+| 插入吞吐量 | ~1,200,000 ops/s |
+| 点查询吞吐量 | ~1,500,000 ops/s |
+| 范围扫描 (1000 keys) | ~0.3 ms |
+
+## 向量引擎基准测试
+
+### HNSW 索引
+
+| 指标 | 值 |
+|------|-----|
+| 插入 (dim=128) | ~45,000 vectors/s |
+| 搜索 top-10 (n=100K) | ~8 ms |
+| 每向量内存 (dim=128) | ~580 bytes |
+
+参数: `M=16`, `efConstruction=200`, `efSearch=64`。
+
+### SIMD 距离函数
+
+| 操作 | dim=128 | dim=768 | dim=1536 |
+|------|---------|---------|----------|
+| Cosine distance | 4.2M/s | 850K/s | 420K/s |
+| L2 (Euclidean) | 4.5M/s | 920K/s | 450K/s |
+| Dot product | 4.8M/s | 980K/s | 480K/s |
+
+## 协议基准测试
+
+| 协议 | 连接数 | 查询/秒 | p99 延迟 |
+|------|--------|---------|----------|
+| Binary (localhost) | 1 | 45,000 | 0.4 ms |
+| Binary (localhost) | 100 | 380,000 | 1.2 ms |
+| HTTP/REST | 1 | 12,000 | 2.1 ms |
+| HTTP/REST | 100 | 95,000 | 5.8 ms |
+
+## 调优指南
+
+### 写密集型工作负载
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=256
+BARADB_WAL_SYNC_INTERVAL_MS=10
+BARADB_COMPACTION_INTERVAL_MS=30000
+```
+
+### 读密集型工作负载
+
+```bash
+BARADB_CACHE_SIZE_MB=1024
+BARADB_BLOOM_BITS_PER_KEY=10
+BARADB_COMPACTION_INTERVAL_MS=120000
+```
+
+### 向量搜索
+
+```bash
+BARADB_VECTOR_EF_CONSTRUCTION=200
+BARADB_VECTOR_EF_SEARCH=128
+BARADB_VECTOR_M=32
+```
+
+### 图分析
+
+```bash
+BARADB_GRAPH_PAGE_RANK_ITERATIONS=20
+BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0
+```
@@ -0,0 +1,67 @@
+# 协议参考
+
+BaraDB 支持多种客户端通信协议：
+- **Binary Wire Protocol** — 高性能、低延迟
+- **HTTP/REST API** — 语言无关、易于调试
+- **WebSocket** — 流式传输和发布/订阅
+
+## Binary Wire Protocol
+
+所有多字节值使用大端编码。
+
+### 连接生命周期
+
+```
+Client                          Server
+  |                               |
+  |─── TCP connect ──────────────>|
+  |─── Auth message ──────────────>|
+  |<── Auth_OK / Error ───────────|
+  |─── Query message ────────────>|
+  |<── Data / Complete / Error ───|
+```
+
+### 消息格式
+
+```
+┌─────────────┬─────────────┬─────────────┬─────────────────────┐
+│  Length     │  Type       │  Sequence   │  Payload            │
+│  (4 bytes)  │  (1 byte)   │  (1 byte)   │  (Length - 6 bytes) │
+└─────────────┴─────────────┴─────────────┴─────────────────────┘
+```
+
+### 消息类型
+
+| 类型 | ID | 描述 |
+|------|----|------|
+| Query | 0x01 | 执行查询 |
+| Insert | 0x02 | 插入数据 |
+| Update | 0x03 | 更新数据 |
+| Delete | 0x04 | 删除数据 |
+| Ready | 0x05 | 准备就绪 |
+| Error | 0x06 | 错误响应 |
+
+## HTTP/REST API
+
+Base URL: `http://localhost:9470/api/v1`
+
+### 端点
+
+#### Health
+
+```http
+GET /health
+```
+
+#### Query
+
+```http
+POST /query
+{
+  "query": "SELECT * FROM users"
+}
+```
+
+## WebSocket Protocol
+
+URL: `ws://localhost:9471`
@@ -0,0 +1,134 @@
+# BaraDB - 快速入门指南
+
+## 启动服务器
+
+构建 BaraDB 后，启动服务器:
+
+```bash
+./build/baradadb
+```
+
+服务器默认在 `localhost:9470` 上启动。
+
+## 通过 CLI 连接
+
+BaraDB 包含一个交互式 shell:
+
+```bash
+./build/baradadb --shell
+```
+
+## 基本操作
+
+### 创建模式
+
+```sql
+CREATE TYPE Person {
+  name: str,
+  age: int32
+};
+
+CREATE TYPE Movie {
+  title: str,
+  year: int32,
+  director: Person
+};
+```
+
+### 插入数据
+
+```sql
+INSERT Person { name := 'Alice', age := 30 };
+INSERT Person { name := 'Bob', age := 25 };
+```
+
+### 查询数据
+
+```sql
+SELECT name, age FROM Person WHERE age > 18;
+```
+
+### 更新数据
+
+```sql
+UPDATE Person SET age = 31 WHERE name = 'Alice';
+```
+
+### 删除数据
+
+```sql
+DELETE FROM Person WHERE name = 'Bob';
+```
+
+## 高级查询
+
+### JOIN
+
+```sql
+SELECT u.name, o.total
+FROM users u
+INNER JOIN orders o ON u.id = o.user_id;
+```
+
+### 聚合
+
+```sql
+SELECT department, count(*), avg(salary)
+FROM employees
+GROUP BY department
+HAVING count(*) > 5;
+```
+
+### CTE (公共表表达式)
+
+```sql
+WITH active_users AS (
+  SELECT * FROM users WHERE active = true
+)
+SELECT * FROM active_users;
+```
+
+## 向量搜索
+
+```sql
+-- 插入向量
+INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] };
+
+-- 搜索相似
+SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;
+```
+
+## 图操作
+
+```sql
+-- 匹配图模式
+MATCH (p:Person)-[:KNOWS]->(other:Person)
+WHERE p.name = 'Alice'
+RETURN other.name;
+```
+
+## 全文搜索
+
+```sql
+-- 搜索文档
+SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database');
+```
+
+## HTTP/REST API
+
+```bash
+# GET 请求
+curl http://localhost:9470/api/users
+
+# POST 请求
+curl -X POST http://localhost:9470/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "age": 30}'
+```
+
+## 下一步
+
+- [BaraQL 参考](baraql.md)
+- [存储引擎](storage.md)
+- [架构概述](architecture.md)
+- [协议参考](protocol.md)
@@ -0,0 +1,46 @@
+# 模式系统
+
+BaraDB 使用 schema-first 设计，支持类型继承和自动迁移。
+
+## 定义类型
+
+```nim
+import barabadb/schema/schema
+
+var s = newSchema()
+
+let person = newType("Person")
+person.addProperty("name", "str", required = true)
+person.addProperty("age", "int32")
+s.addType("default", person)
+```
+
+## 类型继承
+
+```nim
+let employee = newType("Employee")
+employee.setBases(@["Person"])
+employee.addProperty("department", "str")
+s.addType("default", employee)
+```
+
+## 模式操作
+
+### Diff
+
+```nim
+let diff = s.diff(oldSchema, newSchema)
+```
+
+## 属性类型
+
+| 类型 | 描述 |
+|------|------|
+| `str` | 字符串 |
+| `int32` | 32 位整数 |
+| `int64` | 64 位整数 |
+| `float32` | 32 位浮点数 |
+| `float64` | 64 位浮点数 |
+| `bool` | 布尔值 |
+| `datetime` | 日期/时间 |
+| `bytes` | 二进制数据 |
@@ -0,0 +1,188 @@
+# 安全指南
+
+## TLS/SSL 加密
+
+BaraDB 支持所有协议的 TLS 1.3（二进制、HTTP、WebSocket）。如果未提供证书，服务器会在启动时自动生成自签名证书以实现零配置加密。
+
+### 使用自定义证书
+
+```bash
+BARADB_TLS_ENABLED=true \
+BARADB_CERT_FILE=/etc/baradb/server.crt \
+BARADB_KEY_FILE=/etc/baradb/server.key \
+./build/baradadb
+```
+
+### 生成自签名证书
+
+```bash
+openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+### Let's Encrypt（生产环境）
+
+使用 certbot 并将 BaraDB 指向生成的文件：
+
+```bash
+sudo certbot certonly --standalone -d db.example.com
+
+BARADB_CERT_FILE=/etc/letsencrypt/live/db.example.com/fullchain.pem \
+BARADB_KEY_FILE=/etc/letsencrypt/live/db.example.com/privkey.pem \
+./build/baradadb
+```
+
+### 客户端 TLS
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472, tls=True, tls_verify=True)
+client.connect()
+```
+
+## 认证
+
+### 基于 JWT 的认证
+
+BaraDB 使用 HMAC-SHA256 签名的 JWT。
+
+#### 启用认证
+
+```bash
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+#### 创建令牌
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("your-secret-key")
+let token = am.createToken(JWTClaims(
+  sub: "user1",
+  role: "admin",
+  exp: getTime() + 24.hours
+))
+```
+
+#### 基于角色的访问控制
+
+| 角色 | 权限 |
+|------|------|
+| `admin` | 完全访问 |
+| `write` | 读取 + 写入 |
+| `read` | 只读 |
+| `monitor` | 仅指标和健康检查 |
+
+#### 使用令牌
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:9470/api/query \
+  -d '{"query": "SELECT * FROM users"}'
+```
+
+```python
+from baradb import Client
+
+client = Client("localhost", 9472)
+client.connect()
+client.authenticate("eyJhbGciOiJIUzI1NiIs...")
+```
+
+### 多因素认证 (MFA)
+
+```nim
+import barabadb/protocol/auth
+
+var am = newAuthManager("secret-key")
+let mfaCode = am.generateTOTP("user1")
+let valid = am.validateTOTP("user1", mfaCode)
+```
+
+## 限流
+
+Token-bucket 限流防止滥用：
+
+```nim
+import barabadb/protocol/ratelimit
+
+var rl = newRateLimiter(
+  rlaTokenBucket,
+  globalRate = 10000,
+  perClientRate = 1000,
+  burstSize = 100
+)
+
+if not rl.allowRequest("client-ip"):
+  return error("超出限流")
+```
+
+## 网络安全
+
+### 绑定地址
+
+默认 BaraDB 绑定到 `127.0.0.1`（仅本地）。生产环境：
+
+```bash
+BARADB_ADDRESS=0.0.0.0 ./build/baradadb
+```
+
+### 防火墙规则
+
+```bash
+sudo ufw allow from 10.0.0.0/8 to any port 9472
+sudo ufw allow from 10.0.0.0/8 to any port 9470
+sudo ufw deny 9471
+```
+
+## 静态数据加密
+
+### 操作系统级加密
+
+使用 LUKS 进行全磁盘加密：
+
+```bash
+cryptsetup luksFormat /dev/nvme0n1p2
+cryptsetup open /dev/nvme0n1p2 baradb-crypt
+mkfs.ext4 /dev/mapper/baradb-crypt
+mount /dev/mapper/baradb-crypt /var/lib/baradb
+```
+
+### 应用级加密
+
+```bash
+BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
+./build/baradadb
+```
+
+## 审计日志
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00Z",
+  "level": "info",
+  "event": "query_executed",
+  "client_ip": "10.0.0.15",
+  "user": "app_user",
+  "query": "SELECT * FROM users WHERE id = ?",
+  "duration_ms": 12,
+  "rows_returned": 1
+}
+```
+
+## 安全检查清单
+
+- [ ] 更改默认 JWT 密钥
+- [ ] 使用有效证书启用 TLS
+- [ ] 绑定到特定接口
+- [ ] 生产环境启用认证
+- [ ] 配置限流
+- [ ] 启用审计日志
+- [ ] 静态数据加密
+- [ ] 以非 root 用户运行
+- [ ] 保持防火墙规则严格
+- [ ] 定期轮换 JWT 密钥
@@ -0,0 +1,78 @@
+# 存储引擎
+
+BaraDB 提供多种存储引擎，针对不同的访问模式进行了优化。
+
+## LSM-Tree（键值）
+
+主要的存储引擎，采用写优化的追加式日志结构。
+
+### 使用
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key1", cast[seq[byte]]("value1"))
+let (found, value) = db.get("key1")
+db.close()
+```
+
+### 组件
+
+- **MemTable**：内存中的排序缓冲区
+- **WAL**：预写日志，用于持久性
+- **SSTable**：磁盘上的排序字符串表
+- **Bloom Filter**：用于快速否定查找的概率结构
+- **Compaction**：带层级管理的大小分层策略
+- **Page Cache**：带命中率追踪的 LRU 缓存
+
+## B-Tree 索引
+
+用于范围扫描和点查询的有序索引。
+
+### 使用
+
+```nim
+import barabadb/storage/btree
+
+var btree = newBTreeIndex[string, string]()
+btree.insert("key1", "value1")
+let values = btree.get("key1")
+let range = btree.scan("key_a", "key_z")
+```
+
+## 预写日志 (WAL)
+
+确保写操作的持久性。
+
+```nim
+import barabadb/storage/wal
+
+var wal = newWAL("./wal")
+wal.append("txn1", "SET key1 value1")
+wal.flush()
+```
+
+## Bloom 过滤器
+
+用于快速否定查找的概率数据结构。
+
+```nim
+import barabadb/storage/bloom
+
+var filter = newBloomFilter(10000, 0.01)
+filter.add("key1")
+if filter.mightContain("key1"):
+  echo "可能存在"
+```
+
+## 内存映射 I/O
+
+使用 mmap 进行高效的文件访问。
+
+```nim
+import barabadb/storage/mmap
+
+var mapped = mmapFile("./data/file.dat")
+let data = mapped.read(0, 100)
+```
@@ -0,0 +1,77 @@
+# 事务与 MVCC
+
+MVCC（多版本并发控制），提供快照隔离和死锁检测。
+
+## 使用
+
+```nim
+import barabadb/core/mvcc
+
+var tm = newTxnManager()
+let txn = tm.beginTxn()
+
+# 写操作
+discard tm.write(txn, "key1", cast[seq[byte]]("value1"))
+discard tm.write(txn, "key2", cast[seq[byte]]("value2"))
+
+# 保存点
+tm.savepoint(txn)
+discard tm.write(txn, "key3", cast[seq[byte]]("value3"))
+discard tm.rollbackToSavepoint(txn)
+
+# 提交
+discard tm.commit(txn)
+```
+
+## 事务隔离
+
+BaraDB 使用**快照隔离**：
+- 读取者不阻塞写入者
+- 写入者不阻塞读取者
+- 每个事务看到一致的快照
+
+## 死锁检测
+
+```nim
+import barabadb/core/deadlock
+
+var detector = newDeadlockDetector()
+if detector.detectCycle(txn1, txn2):
+  echo "检测到死锁！"
+```
+
+## 预写日志
+
+```nim
+import barabadb/storage/wal
+
+var wal = newWAL("./wal")
+wal.append(txnId, "SET key value")
+wal.flush()
+```
+
+## 保存点
+
+嵌套事务保存点：
+
+```nim
+tm.savepoint(txn, "sp1")
+tm.rollbackToSavepoint(txn, "sp1")
+```
+
+## 形式化验证
+
+MVCC/快照隔离协议在 TLA+ 中形式化规范：
+
+- **规范：** `formal-verification/mvcc.tla`
+- **验证的属性：**
+  - `NoDirtyReads` — 事务从不读取未提交的数据
+  - `ReadOwnWrites` — 事务总是看到自己的写入
+  - `WriteWriteConflict` — 先提交者胜出
+
+本地运行 TLC：
+
+```bash
+cd formal-verification
+java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla
+```
@@ -0,0 +1,118 @@
+# 故障排除指南
+
+## 安装问题
+
+### 未找到 Nim
+
+```bash
+curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+```
+
+### SSL 编译错误
+
+```bash
+nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim
+```
+
+### 缺少依赖
+
+```bash
+nimble install -d -y
+```
+
+## 运行时问题
+
+### 端口已被占用
+
+```bash
+BARADB_PORT=5433 ./build/baradadb
+lsof -ti:9472 | xargs kill -9
+```
+
+### 权限被拒绝
+
+```bash
+mkdir -p ./data
+chmod 755 ./data
+```
+
+### 内存不足
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=32 \
+BARADB_CACHE_SIZE_MB=128 \
+BARADB_VECTOR_EF_CONSTRUCTION=100 \
+./build/baradadb
+```
+
+### 磁盘已满
+
+```bash
+curl -X POST http://localhost:9470/api/admin/compact
+./build/baradadb --compact
+```
+
+## 查询问题
+
+### 语法错误
+
+```sql
+SELECT name, age FROM users WHERE age > 18;
+```
+
+### 表未找到
+
+```sql
+CREATE TYPE User { name: str, age: int32 };
+```
+
+### 类型不匹配
+
+```sql
+SELECT * FROM users WHERE age > 18;
+```
+
+## 连接问题
+
+### 连接被拒绝
+
+```bash
+./build/baradadb
+sudo ufw allow 9472
+```
+
+### 认证失败
+
+```bash
+BARADB_AUTH_ENABLED=true \
+BARADB_JWT_SECRET="correct-secret" \
+./build/baradadb
+```
+
+## 性能问题
+
+### 查询慢
+
+1. 创建索引：`CREATE INDEX idx_users_name ON users(name);`
+2. 使用 LIMIT
+3. 增加缓存：`BARADB_CACHE_SIZE_MB=1024`
+
+### 高 CPU 使用率
+
+```bash
+BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb
+```
+
+### 高内存使用
+
+```bash
+BARADB_MEMTABLE_SIZE_MB=64
+BARADB_CACHE_SIZE_MB=256
+BARADB_VECTOR_M=8
+```
+
+## 调试模式
+
+```bash
+BARADB_LOG_LEVEL=debug ./build/baradadb
+```
@@ -0,0 +1,47 @@
+# 用户定义函数
+
+使用自定义函数扩展 BaraQL。
+
+## 用法
+
+```nim
+import barabadb/query/udf
+
+var reg = newUDFRegistry()
+
+reg.registerStdlib()
+
+reg.register("greet", @[UDFParam(name: "name", typeName: "str")],
+  "str", proc(args: seq[Value]): Value =
+    return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!"))
+```
+
+## 标准库函数
+
+| 函数 | 描述 | 示例 |
+|------|------|------|
+| `abs(n)` | 绝对值 | `abs(-5)` → 5 |
+| `sqrt(n)` | 平方根 | `sqrt(16)` → 4 |
+| `pow(n, e)` | 幂 | `pow(2, 3)` → 8 |
+| `lower(s)` | 小写 | `lower('ABC')` → 'abc' |
+| `upper(s)` | 大写 | `upper('abc')` → 'ABC' |
+| `len(s)` | 长度 | `len('hello')` → 5 |
+| `trim(s)` | 去空格 | `trim(' hello ')` → 'hello' |
+
+## 注册函数
+
+```nim
+reg.register(
+  name: "my_function",
+  params: @[UDFParam(name: "arg1", typeName: "str")],
+  returnType: "str",
+  body: proc(args: seq[Value]): Value =
+    result = Value(kind: vkString, strVal: "")
+)
+```
+
+## 在查询中使用 UDF
+
+```sql
+SELECT greet(name) FROM users;
+```
@@ -0,0 +1,65 @@
+# 向量搜索引擎
+
+用于相似性搜索的本机 HNSW 和 IVF-PQ 索引。
+
+## 用法
+
+```nim
+import barabadb/vector/engine
+
+var idx = newHNSWIndex(dimensions = 128)
+idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable)
+
+let results = idx.search(queryVector, k = 10)
+```
+
+## 索引类型
+
+### HNSW
+
+用于近似最近邻搜索的分层可导航小世界图。
+
+```nim
+var hnsw = newHNSWIndex(
+  dimensions = 128,
+  m = 16,
+  efConstruction = 200,
+  efSearch = 100
+)
+```
+
+### IVF-PQ
+
+带乘积量化的倒排文件索引。
+
+```nim
+var ivfpq = newIVFPQIndex(
+  dimensions = 128,
+  numCentroids = 256,
+  subQuantizers = 8
+)
+```
+
+## 距离度量
+
+| 度量 | 描述 |
+|------|------|
+| `cosine` | 余弦相似度 |
+| `euclidean` | L2 距离 |
+| `dotproduct` | 点积相似度 |
+| `manhattan` | L1 距离 |
+
+## 量化
+
+```nim
+let scalar = scalarQuantize(data, bits = 8)
+let pq = productQuantize(data, subVectors = 8, bits = 8)
+```
+
+## SIMD 加速
+
+```nim
+import barabadb/vector/simd
+
+let dist = simdCosineDistance(vec1, vec2)
+```