From ac1298ca7fb8603cd6e945ef933c93f48f93407e Mon Sep 17 00:00:00 2001 From: Grigorii Safronov Date: Sun, 8 Sep 2024 11:18:49 +0000 Subject: [PATCH] =?UTF-8?q?=D0=A3=D0=B4=D0=B0=D0=BB=D0=B8=D1=82=D1=8C=20'c?= =?UTF-8?q?ozo-bin/README-zh.md'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- cozo-bin/README-zh.md | 93 ------------------------------------------- 1 file changed, 93 deletions(-) delete mode 100644 cozo-bin/README-zh.md diff --git a/cozo-bin/README-zh.md b/cozo-bin/README-zh.md deleted file mode 100644 index d883389a..00000000 --- a/cozo-bin/README-zh.md +++ /dev/null @@ -1,93 +0,0 @@ -# Cozo（独立程序） - -[![server](https://img.shields.io/github/v/release/cozodb/cozo)](https://github.com/cozodb/cozo/releases) - -本文叙述的是如何安装设置 Cozo 的独立程序本身。有关如何使用 -CozoDB（CozoScript）的信息，见 [文档](https://docs.cozodb.org/zh_CN/latest/index.html) 。 - -## 下载 - -独立服务的程序可以从 [GitHub 发布页](https://github.com/cozodb/cozo/releases) -或 [Gitee 发布页](https://gitee.com/cozodb/cozo/releases) 下载，其中名为 `cozo-*` 的是独立服务程序，名为 `cozo_all-*` -的独立程序同时支持更多地存储引擎，比如 [TiKV](https://tikv.org/)。 - -## 启动服务程序 - -在终端中执行： - -```bash -./cozo server -``` - -如此执行命令会使用纯内存的非持久化存储引擎。执行 `./cozo server -h` 可查看如何启用其它引擎，以及其它参数。 - -若要终止程序，按下 `CTRL-C` 按键，或向进程发送 `SIGTERM` （比如通过 `kill` 命令）。 - -## 命令行界面 - -`./cozo repl` 可开启命令行界面（REPL），同时不会启动 web 服务。其它选择存储引擎的参数可一同使用。 - -在界面中可以使用以下特殊命令： - -* `%set <键> <值>`：设置在查询中可用的参数值。 -* `%unset <键>`：删除已设置的参数值。 -* `%clear`：清空所有已设置的参数。 -* `%params`：显示当前所有参数。 -* `%run <文件>`: 运行 `<文件>` 中包含的查询。 -* `%import <文件或 URL>`：将文件或 URL 里的 JSON 数据导入至数据库。 -* `%save <文件>`：下一个成功查询的结果将会以 JSON 格式存储在指定的文件中。如果文件参数未给出，则清除上次的文件设置。 -* `%backup <文件>`：备份全部数据至指定的文件。 -* `%restore <文件>`：将指定的备份文件中的数据加载到当前数据库中。当前数据库必须为空。 - -## 查询 API - -查询通过向 API 发送 POST 请求来完成。默认的请求地址是 `http://127.0.0.1:9070/text-query` 。请求必须包含 JSON 格式的正文，具体内容如下： - -```json -{ - "script": "", - "params": {} -} -``` - -`params` 给出了查询文本中可用的变量。例如，当 `params` 为 `{"num": 1}` 时，查询文本中可以以 `$num` 来代替常量 `1` -。请善用此功能，而不是手动拼接查询字符串。 - -HTTP API 返回的结果永远是 JSON 格式的。如果请求成功，则返回结果的 `"ok"` 字段将为 `true`，且 `"rows"` -字段将含有查询结果的行，而 `"headers"` 将含有表头。如果查询报错，则 `"ok"` 字段将为 `false`，而错误信息会在 `"message"` -字段中，同时 `"display"` 字段会包含格式化好的友好的错误提示。 - -> Cozo 的设计，基于其在一个受信任的环境中运行，且其所有用户也是由受信任的这种假设。因此 Cozo 没有内置认证与复杂的安全机制。如果你需要远程访问 -> Cozo 服务，你必须自己设置防火墙、加密和代理等，用来保护服务器上资源的安全。 -> -> 由于总是会有用户不小心将服务接口暴露于外网，Cozo 有一个补救措施：如果允许了非回传地址访问 Cozo，则必须在所有请求中以 HTTP -> 文件头 `x-cozo-auth` 的形式附上访问令牌。访问令牌的内容在启动服务的终端中有提示。注意这仅仅是一个补救措施，并不是特别可靠的安全机制，是为了尽量防止一些不由于小心而造成严重后果的悲剧。 -> -> 在有些客户端里，部分 API 加入 HTTP 文件头可能会比较困难或者根本不可能。这时也可以在查询参数 `auth` 中传入令牌。 - -## 所有 API - -* `POST /text-query`，见上。 -* `GET /export/{relations: String}`，导出指定表中的数据，其中 `relations` 是以逗号分割的表名。 -* `PUT /import`，向数据库导入数据。所导入的数据应以在正文中以 `application/json` MIME 类型传入，具体格式与 `/export` - 返回值中的 `data` 字段相同。 -* `POST /backup`，备份数据库，需要传入 JSON 正文 `{"path": <路径>}`。 -* `POST /import-from-backup`，将备份中指定存储表中的数据插入当前数据库中同名存储表。需要传入 JSON - 正文 `{"path": <路径>, "relations": <表名数组>}`. -* `GET /`，用浏览器打开这个地址，然后打开浏览器的调试工具，就可以使用一个简陋的 JS 客户端。 - -> 注意 `import` 与 `import-from-backup` 接口不会激活任何触发器。 - - -以下为试验性的 API： - -* `GET(SSE) /changes/{relation: String}` - 获取某个存储表的更新，基于 [SSE](https://developer.mozilla.org/zh-CN/docs/Web/API/Server-sent_events/Using_server-sent_events). - -## 编译 - -编译 `cozo` 需要 [Rust 工具链](https://rustup.rs)。运行 - -```bash -cargo build --release -p cozo-bin -F compact -F storage-rocksdb -```