# SurrealDB 3 技能专家级 SurrealDB 3 架构、开发和运营。涵盖 SurrealQL、多模型数据建模、图遍历、向量搜索、安全、部署、性能调优、SDK 集成以及完整的 SurrealDB 生态系统。 ## 对于人工智能代理获取完整的功能清单、决策树和输出合同： uv run {baseDir}/scripts/onboard.py --agent 有关完整的结构化简报，请参阅 [AGENTS.md]()。命令 |它的作用 ---|--- `uv 运行 {baseDir}/scripts/doctor.py` |健康检查：验证超现实的 CLI、连接性、版本 `uv run {baseDir}/scripts/doctor.py --check` |快速通过/失败检查（仅限退出代码） `uv 运行 {baseDir}/scripts/schema.py introspect` |转储正在运行的 SurrealDB 实例的完整架构 `uv 运行 {baseDir}/scripts/schema.py 表` |列出包含字段计数和索引的所有表 `uv run {baseDir}/scripts/onboard.py --agent` |用于代理集成的 JSON 功能清单 ## 先决条件 * **surreal CLI** \-- `brew install surrealdb/tap/surreal` (macOS) 或参阅 [安装文档]() * **Python 3.10+** \-- 技能脚本所需 * **uv** \-- `brew install uv` (macOS) 或 `pip install uv` 或参阅 [uv 文档]() 可选： * **Docker** \-- 对于容器化 SurrealDB 实例（`docker run surrealdb/surrealdb:v3`） * **选择 SDK** \-- JavaScript、Python、Go、Rust、Java、.NET、C、PHP 或 Dart > **安全说明**：此技能的文档引用包管理器安装（brew、pip、cargo、npm、Docker）作为推荐的安装方法。如果遇到`curl | sh` 规则文件中的示例，更喜欢您的操作系统包管理器或下载和审查工作流程。 ## 快速入门 > **凭据警告**：下面的示例使用 `root/root` 进行 **本地开发**。切勿对生产或共享实例使用默认凭据。为非本地环境创建范围有限、权限最低的用户。 # 在内存中启动 SurrealDB 仅用于本地开发超现实启动内存 --user root --pass root --bind 127.0.0.1:8000 # 从持久性 RocksDB 存储开始（本地开发）超现实启动rocksdb://data/mydb.db --user root --pass root # 从 SurrealKV 开始（支持时间旅行查询，本地开发） surreal启动 surrealkv://data/mydb --user root --pass root # 通过 CLI REPL 连接（本地开发）超现实的sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test # 导入 SurrealQL 文件超现实导入 --endpoint http://localhost:8000 --user root --pass root --ns test --db test schema.surql # 导出数据库超现实导出 --endpoint http://localhost:8000 --user root --pass root --ns test --db test backup.surql # 检查版本超现实版本 # 运行技能健康检查 uv 运行 {baseDir}/scripts/doctor.py ## 环境变量变量|描述 |默认 ---|---|--- `SURREAL_ENDPOINT` | SurrealDB 服务器 URL | `http://localhost:8000` `SURREAL_USER` |根或命名空间用户名 | `根` `SURREAL_PASS` |根或名称空间密码 | `根` `SURREAL_NS` |默认命名空间 | `测试` `SURREAL_DB` |默认数据库 | `测试` 这些直接映射到“surreal sql”CLI 标志（“--endpoint”、“--user”、“--pass”、“--ns”、“--db”），并被官方 SurrealDB SDK 识别。 ## 核心能力 ### SurrealQL 掌握全面覆盖 SurrealQL 查询语言：`CREATE`、`SELECT`、`UPDATE`、`UPSERT`、`DELETE`、`RELATE`、`INSERT`、`LIVE SELECT`、`DEFINE`、`REMOVE`、`INFO`、子查询、事务、期货和所有内置函数（数组、加密、持续时间、地理、数学、元、对象、解析、兰特、字符串、时间、类型、向量）。请参阅：`rules/surrealql.md` ### 多模型数据建模设计模式利用 SurrealDB 的多模型功能（文档集合、图形边缘、关系引用、向量嵌入、时间序列数据和地理空间坐标），所有这些都在使用单一查询语言的单个数据库中。请参阅：`rules/data-modeling.md` ### 图查询无需 JOIN 的一流图遍历。 “RELATE”在记录之间创建类型边缘。使用“->”（传出）、“<-”（传入）和“<->”（双向）运算符进行遍历。在任意深度进行过滤、聚合和递归。请参阅：`rules/graph-queries.md` ### 矢量搜索使用 HNSW 和强力索引的内置向量相似性搜索。定义向量场，使用可配置的距离度量（余弦、欧几里得、曼哈顿、明科斯基）创建索引，并使用“vector::similarity::*”函数进行查询。直接在 SurrealQL 中构建 RAG 管道和语义搜索。请参阅：`rules/vector-search.md` ### 安全和权限通过“DEFINE TABLE ... PERMISSIONS”、命名空间/数据库/记录级访问控制、用于 JWT/基于令牌的身份验证的“DEFINE ACCESS”、用于系统用户的“DEFINE USER”以及用于权限谓词的“$auth”/“$session”运行时变量来实现行级安全性。请参阅：`rules/security.md` ### 部署和操作单二进制部署、Docker、Kubernetes（Helm 图表）、存储引擎选择（分布式的内存、RocksDB、SurrealKV、TiKV）、备份/恢复、监控和生产强化。请参阅：`rules/deployment.md` ### 性能调整索引策略（唯一、搜索、向量 HNSW、MTree）、使用“EXPLAIN”进行查询优化、连接池、存储引擎权衡、批处理操作和资源限制。请参阅：`rules/performance.md` ### SDK集成适用于 JavaScript/TypeScript（Node.js、Deno、Bun、浏览器）、Python、Go、Rust、Java、.NET、C、PHP 和 Dart 的官方 SDK。连接协议（HTTP、WebSocket）、身份验证流、实时查询订阅和类型化记录处理。请参阅：`rules/sdks.md` ### 超现实主义 WASM 扩展 SurrealDB 3 中的新增功能：使用 Rust 编写并编译为 WASM 的自定义函数、分析器和逻辑来扩展数据库。定义、部署和管理超现实主义模块。请参阅：`rules/surrealism.md` ### 生态系统工具 * **Surrealist** \-- SurrealDB 的官方 IDE 和 GUI（模式设计器、查询编辑器、图形可视化器） * **Surreal-Sync** \-- 用于从其他数据库迁移的更改数据捕获 (CDC) * **SurrealFS** \-- 基于 SurrealDB 构建的 AI 代理文件系统 * **SurrealML** \-- SurrealDB 中的机器学习模型管理和推理请参阅：`rules/surrealist.md`、`rules/surreal-sync.md`、`rules/surrealfs.md` ## 医生/健康检查 # 完整诊断（标准错误上的丰富输出，标准输出上的 JSON） uv 运行 {baseDir}/scripts/doctor.py # 快速检查（退出代码 0 = 正常，1 = 发现问题） uv run {baseDir}/scripts/doctor.py --check # 检查特定端点 uv run {baseDir}/scripts/doctor.py --endpoint http://my-server:8000 doctor 脚本验证：已安装超现实 CLI 并位于 PATH 上、服务器可访问、身份验证成功、命名空间和数据库存在、版本兼容性以及存储引擎状态。 ## 模式自省 # 完整模式转储（所有表、字段、索引、事件、访问） uv 运行 {baseDir}/scripts/schema.py introspect # 列出带有摘要的表 uv 运行 {baseDir}/scripts/schema.py 表 # 检查特定表 uv run {baseDir}/scripts/schema.py table # 将模式导出为 SurrealQL（可重现的 DEFINE 语句） uv run {baseDir}/scripts/schema.py 导出 --format surql # 将模式导出为 JSON uv run {baseDir}/scripts/schema.py 导出 --format json 内省使用“INFO FOR DB”、“INFO FOR TABLE”和“INFO FOR NS”来重建完整模式。 ## 规则参考规则文件 |覆盖范围 ---|--- `规则/surrealql.md` | SurrealQL 语法、语句、函数、运算符、习语 `规则/数据建模.md` |模式设计、记录 ID、字段类型、关系、规范化 `rules/graph-queries.md` | RELATE、图遍历运算符、路径表达式、递归查询 `规则/向量搜索.md` |向量场、HNSW/暴力索引、相似函数、RAG 模式 `规则/security.md` |权限、访问控制、身份验证、JWT、行级安全 `规则/部署.md` |安装、存储引擎、Docker、Kubernetes、生产配置 `规则/性能.md` |索引、EXPLAIN、查询优化、批处理操作、资源调优 `规则/sdks.md` | JavaScript、Python、Go、Rust SDK 使用、连接模式、实时查询 `规则/超现实主义.md` | WASM 扩展、自定义函数、超现实主义模块创作 `规则/超现实主义.md` |超现实主义 IDE/GUI 使用、模式设计器、查询编辑器 `rules/surreal-sync.md` | CDC 迁移工具、源/目标连接器、迁移工作流程 `规则/surrealfs.md` | AI代理文件系统、文件存储、元数据、检索模式 ## 工作流程示例 > **所有工作流程示例仅使用“root/root”进行本地开发。**对于生产，请使用“DEFINE USER”和范围内的、最低权限的凭据。 ### 新项目设置 # 1.验证环境 uv 运行 {baseDir}/scripts/doctor.py # 2.启动SurrealDB 超现实启动rocksdb://data/myproject.db --user root --pass root # 3.设计模式（使用rules/data-modeling.md作为指导） # 4. 导入初始模式超现实导入 --endpoint http://localhost:8000 --user root --pass root \ --ns myapp --db 生产 schema.surql # 5. 内省验证 uv 运行 {baseDir}/scripts/schema.py introspect ### 从 SurrealDB v2 迁移 # 1.导出v2数据超现实导出 --endpoint http://old-server:8000 --user root --pass root \ --ns myapp --db 生产 v2-backup.surql # 2. 查看重大更改（请参阅rules/surrealql.md v2->v3 迁移部分） # 关键变化：范围语法 1..4 现在不包含 end，新的 WASM 扩展系统 # 3.导入v3 超现实导入 --endpoint http://localhost:8000 --user root --pass root \ --ns myapp --db 生产 v2-backup.surql # 4. 验证架构 uv 运行 {baseDir}/scripts/schema.py introspect ### 新领域的数据建模 # 1. 阅读rules/data-modeling.md以了解模式设计模式 # 2. 如果您的域有关系，请阅读rules/graph-queries.md # 3.如果需要语义搜索，请阅读rules/vector-search.md # 4. 使用 DEFINE TABLE、DEFINE Field、DEFINE INDEX 草稿 schema.surql # 5.导入并测试超现实导入 --endpoint http://localhost:8000 --user root --pass root \ --ns dev --db 测试 schema.surql uv 运行 {baseDir}/scripts/schema.py introspect ### 部署到生产环境 # 1. 阅读rules/deployment.md进行存储引擎选择和强化 # 2. 读取rules/security.md进行访问控制设置 # 3. 阅读rules/performance.md获取索引策略 # 4. 针对生产端点运行 doctor uv run {baseDir}/scripts/doctor.py --endpoint https://prod-surreal:8000 # 5. 验证架构是否符合预期 uv run {baseDir}/scripts/schema.py introspect --endpoint https://prod-surreal:8000 ## 上游来源检查 # 检查自该技能构建以来上游 SurrealDB 存储库是否已更改 uv 运行 {baseDir}/scripts/check_upstream.py # 代理的纯 JSON 输出 uv run {baseDir}/scripts/check_upstream.py --json # 只显示有新提交的存储库 uv run {baseDir}/scripts/check_upstream.py --stale 将所有跟踪的存储库的当前 HEAD SHA 和发布标签与“SOURCES.json”中的基线进行比较。用它来计划增量技能更新。 ## 来源出处该技能是在 **2026-02-19** 上从这些上游来源构建的：存储库 |发布 |快照日期 ---|---|--- [surrealdb/surrealdb]() | v3.0.0 | 2026-02-19 [surrealdb/surrealist]() | v3.7.2 | 2026-02-21 [surrealdb/surrealdb.js]() | v1.3.2 | 2026-02-20 [surrealdb/surrealdb.js]() (v2 beta) | v2.0.0-beta.1 | 2026-02-20 [surrealdb/surrealdb.py]() | v1.0.8 | 2026-02-03 [surrealdb/surrealdb.go]() | v1.3.0 | 2026-02-12 [surrealdb/surreal-sync]() | v0.3.4 | 2026-02-12 [surrealdb/surrealfs]() | \-- | 2026-01-29 文档：[surrealdb.com/docs]() 快照 2026 年 2 月 22 日。机器可读来源：`SOURCES.json`。 ## 输出约定本技能中的所有 Python 脚本都遵循双输出模式： * **stderr** ：丰富格式的人类可读输出（表格、面板、状态指示器） * **stdout** ：机器可读的 JSON，供 AI 代理以编程方式使用这意味着 `2>/dev/null` 隐藏了人工输出，并且管道 stdout 为下游处理提供了干净的 JSON。

超现实数据库

包含技能