joepmeneer/atomic-server

atomic-server

![crates.io]([] ![ chat]([***]

状态：Beta版。1.0版本前可能会有重大变更。

Atomic-server是一款用于存储和共享Atomic Data的图数据库服务器。演示地址：atomicdata.dev

• 🚀 高性能（在作者的笔记本电脑上中位响应时间为1ms），基于https://github.com/actix/actix-web%E5%92%8Chttps://github.com/spacejam/sled%E6%9E%84%E5%BB%BA
• 🪶 轻量级（下载大小8MB，无运行时依赖）
• 💻 跨平台运行（Linux、Windows、macOS、ARM架构）
• ⚛️ 动态schema验证/类型检查，基于Atomic Schema
• 🌐 嵌入式服务器，支持HTTP/HTTPS/HTTP2.0及内置Let's Encrypt握手功能
• 🎛️ 内置浏览器GUI，由https://github.com/atomicdata-dev/atomic-data-browser%E6%8F%90%E4%BE%9B%E6%94%AF%E6%8C%81%EF%BC%8C%E5%85%B7%E5%A4%87%E5%8A%A8%E6%80%81%E8%A1%A8%E5%8D%95%E3%80%81%E8%A1%A8%E6%A0%BC%E3%80%81%E8%BA%AB%E4%BB%BD%E9%AA%8C%E8%AF%81%E3%80%81%E4%B8%BB%E9%A2%98%E8%AE%BE%E7%BD%AE%E7%AD%89%E5%8A%9F%E8%83%BD
• 💾 事件溯源版本控制/历史记录，基于Atomic Commits
• 🔄 WebSocket同步：与客户端通信状态变更
• 🧰 多种序列化选项：支持JSON、JSON-AD及多种关联数据/RDF格式（RDF/XML、N-Triples/Turtle/JSON-LD）
• 🔎 全文搜索，支持模糊搜索和多种运算符，响应时间通常<3ms，基于https://github.com/quickwit-inc/tantivy
• 📖 分页、排序和过滤查询，基于Atomic Collections
• 🔐 授权机制（读写权限）和层级结构，基于Atomic Hierarchy
• 📲 邀请和共享系统，基于Atomic Invites
• 📂 文件管理：支持附件上传、下载和预览
• 🖥️ 桌面应用：简易桌面安装，带状态栏图标，基于https://github.com/tauri-apps/tauri/

基于Rust、atomic-lib等技术构建。

目录

• 何时使用此镜像
• 何时不建议使用
• 安装与快速开始
  • 使用Docker运行
• 初始设置与配置
  • 使用隧道服务运行（简易模式）
  • 在VPS上设置HTTPS（需静态IP）
• 使用方法
  • 通过浏览器GUI使用Atomic-Server
  • 使用atomic-cli作为客户端
  • API
• 常见问题与故障排除

何时使用此镜像

• 你需要一个功能强大、轻量级、快速且易于使用的CMS，具备编辑器、建模能力和直观的API
• 你希望（高价值）数据集尽可能易于访问
• 你需要为特定领域或数据集指定和共享通用词汇表/本体/模式。示例类见此处
• 你希望使用和共享关联数据，但不想处理RDF的大部分复杂性、SPARQL、三元组存储、命名图和空白节点
• 你对网络的重新去中心化感兴趣，或希望使用改善数据所有权和互操作性的技术
• 你喜欢尝试前沿技术（此应用尚未准备好用于生产环境）

何时不建议使用

• 如果你需要稳定性，请选择其他方案（目前为测试版，可能会有变更）
• 你正在处理敏感/私有数据。授权机制相对较新，尚未经过严格测试
• 有复杂的查询需求。可考虑NEO4j、Apache Jena或TerminusDB

安装与快速开始

你可以通过以下方式运行atomic-server：

使用Docker运行

Dockerfile位于项目根目录。

sh
# 基本运行命令
docker run -p 80:80 -p 443:443 -v atomic-storage:/atomic-storage joepmeneer/atomic-server

# 如需修改端口等参数，可传递相关CLI选项，例如
docker run -p 9883:9883 -v atomic-storage:/atomic-storage joepmeneer/atomic-server --port 9883

# 更新镜像
docker pull joepmeneer/atomic-server

初始设置与配置

• 可通过传递参数（见atomic-server --help）或设置环境变量来配置服务器
• 服务器默认从当前路径加载.env文件。使用atomic-server setup-env命令可在当前目录创建基于默认模板的.env文件
• 运行服务器后，查看日志并记录Agent Subject和Private key。这些信息用于在atomic-cli和https://github.com/atomicdata-dev/atomic-data-browser%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%B8%AD%E8%BF%9B%E8%A1%8C%E6%8E%88%E6%9D%83
• 会创建目录~/.config/atomic，用于存储新创建的Agent密钥、HTTPS证书和其他配置。根据操作系统，实际数据存储位置不同。如需查找文件，可使用show-config命令
• 访问http://localhost:9883/setup以注册第一个（管理员）用户。你可以使用现有Agent或创建新Agent。注意，若创建localhostAgent，则无法在网络上使用（因为它是本地的）

使用隧道服务运行（简易模式）

如果你希望将atomic-server部署到网络，但不想（或无法）处理端口转发和DNS设置，可使用隧道服务。这是将服务器部署到网络的最简单方式，同时仍能完全控制服务器。

• 在隧道服务（如tunnelto.dev）上创建账户，确保保留子域名以保持稳定性
• 运行隧道：tunnelto --port 9883 --subdomain joepio --key YOUR_API_KEY
• 启动服务器：atomic-server --domain joepio.tunnelto.dev --custom-server-url 'https://joepio.tunnelto.dev' --initialize

在VPS上设置HTTPS（需静态IP）

你可能希望通过HTTPS在服务器上提供Atomic Data。可使用由LetsEncrypt、acme_lib和https://github.com/ctz/rustls%E6%94%AF%E6%8C%81%E7%9A%84%E5%B5%8C%E5%85%A5%E5%BC%8FHTTPS/TLS%E8%AE%BE%E7%BD%AE%E3%80%82

通过传递以下标志实现：

sh
# 运行服务器，替换为你的邮箱和域名
atomic-server --https --email some@example.com --domain example.com

也可通过.env文件或其他方式设置这些参数。

确保服务器在ATOMIC_DOMAIN的80端口可访问，因为Let's Encrypt会向服务器的/.well-known目录发送HTTP请求以检查密钥。默认HTTP端口为9883，HTTPS端口为9884。若公开运行服务器，建议设置为80和443：

sh
atomic-server --https --port 80 --port-https 443 --email some@example.com --domain example.com

服务器将初始化证书。查看日志以监控错误。

HTTPS证书在服务器重启且证书使用4周或更久时会自动更新，存储在.config/atomic/目录中。

使用方法

有三种与服务器交互的方式：

通过浏览器GUI使用Atomic-Server

在浏览器中打开服务器，默认地址为http://localhost:9883。

首次访问会显示你的_Drive_（可视为根文件夹），即根URL托管的资源，相当于服务器的主页。

屏幕上会有关于/setup页面的说明。点击进入，会显示_Invite_。通常可点击"Accept as new user"创建新用户，但在localhost上创建的Agent无法在网络上使用。因此，建议在其他运行的服务器（如AtomicData.dev的演示邀请）上创建Agent，然后从AtomicData.dev的"User settings"面板复制密钥，返回localhost版本，点击"sign in"并粘贴密钥即可登录。

登录后再次访问/setup，点击"Accept as {user}"，你的Agent将获得Drive的write权限。可通过悬停描述字段、点击编辑图标进行修改来验证，也可点击菜单栏（左上角三点）并选择"Data view"查看write字段后的Agent。现在你可以编辑所有字段，并以多种格式获取数据。

使用atomic-cli作为客户端

atomic-cli是用于与atomic-server交互的终端应用。

API

可通过向资源URL发送GET请求获取单个项目：

sh
# 获取JSON-AD格式（Atomic Data的默认格式）
curl -i -H "Accept: application/ad+json" https://atomicdata.dev/properties/shortname

# 获取JSON-LD格式
curl -i -H "Accept: application/ld+json" https://atomicdata.dev/properties/shortname

# 获取JSON格式
curl -i -H "Accept: application/json" https://atomicdata.dev/properties/shortname

# 获取Turtle/N3格式
curl -i -H "Accept: text/turtle" https://atomicdata.dev/properties/shortname

更多HTTP请求示例见./example_requests.http。部分API通过Swagger/OpenAPI文档化，可访问https://editor.swagger.io/?url=https://raw.githubusercontent.com/joepio/atomic-data-rust/master/server/openapi.yml%E6%9F%A5%E7%9C%8B%E3%80%82%E4%B9%9F%E5%8F%AF%E9%98%85%E8%AF%BBAtomic Data文档了解Collections、Commits、JSON-AD等概念。

常见问题与故障排除

能否/是否应该创建备份？

应该创建备份，尤其是在安装新版本Atomic-Server前（可能存在数据库模型不兼容导致数据损坏的风险）。使用atomic-server export在~/.config/atomic/backups文件夹中创建备份，通过atomic-server import -p ~/.config/atomic/backups/${date}.json导入。

丢失Root Agent的密钥，且/setup邀请不再可用，该怎么办？

运行atomic-server --initialize可重新创建/setup邀请，将其重置为1次使用。

如何将数据迁移到新域名？

目前没有辅助函数，但可使用atomic-server export导出JSON-AD，然后查找并替换旧域名。这在从localhost:9883迁移到生产服务器时特别有用。

如何重置数据库？

删除atomic配置中的db文件夹：rm -rf ~/.config/atomic/db。

如何使数据私有但仍可在线访问？

点击导航栏中的菜单图标（三点），进入共享设置，取消勾选公共read权限。有关授权模型的更多信息，见文档中的层级章节。

集合/搜索结果中缺少项目？

可能是索引问题。尝试使用atomic-server --rebuild-index重建索引。如有可能，请在问题跟踪器中描述索引问题以便修复。

打开时出现failed to retrieve错误？

尝试重新初始化服务器：atomic-server --initialize。

什么是rdf-search模式？

此模式将atomic-server转换为索引RDF Turtle文档的全文搜索服务器。详见README。

能否将Atomic-Server嵌入其他应用？

可以。作者在Atomic-Server的Tauri桌面版中就是这样做的。示例代码见https://github.com/joepio/atomic-data-rust/tree/master/desktop%E7%9B%AE%E5%BD%95%E3%80%82

数据存储在机器的哪个位置？

取决于操作系统，因为部分数据是临时的，部分是配置文件等。运行atomic-server show-config可查看使用的路径。如需修改，可参考--help中的说明。