atomic-server

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

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

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

🚀 高性能（在作者的笔记本电脑上中位响应时间为1ms），基于actix-web和sled构建
🪶 轻量级（下载大小8MB，无运行时依赖）
💻 跨平台运行（Linux、Windows、macOS、ARM架构）
⚛️ 动态schema验证/类型检查，基于Atomic Schema
🌐 嵌入式服务器，支持HTTP/HTTPS/HTTP2.0及内置Let's Encrypt握手功能
🎛️ 内置浏览器GUI，由atomic-data-browser提供支持，具备动态表单、表格、身份验证、主题设置等功能
💾 事件溯源版本控制/历史记录，基于Atomic Commits
🔄 WebSocket同步：与客户端通信状态变更
🧰 多种序列化选项：支持JSON、JSON-AD及多种关联数据/RDF格式（RDF/XML、N-Triples/Turtle/JSON-LD）
🔎 全文搜索，支持模糊搜索和多种运算符，响应时间通常<3ms，基于tantivy
📖 分页、排序和过滤查询，基于Atomic Collections
🔐 授权机制（读写权限）和层级结构，基于Atomic Hierarchy
📲 邀请和共享系统，基于Atomic Invites
📂 文件管理：支持附件上传、下载和预览
🖥️ 桌面应用：简易桌面安装，带状态栏图标，基于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和atomic-data-browser客户端中进行授权
会创建目录~/.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 '[***] --initialize

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

你可能希望通过HTTPS在服务器上提供Atomic Data。可使用由LetsEncrypt、acme_lib和rustls支持的嵌入式HTTPS/TLS设置。

通过传递以下标志实现：

sh
# 运行服务器，替换为你的***和域名
atomic-server --https --email *** --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 *** --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" [***]

# 获取JSON-LD格式
curl -i -H "Accept: application/ld+json" [***]

# 获取JSON格式
curl -i -H "Accept: application/json" [***]

# 获取Turtle/N3格式
curl -i -H "Accept: text/turtle" [***]

更多HTTP请求示例见./example_requests.http。部分API通过Swagger/OpenAPI文档化，可访问此处查看。也可阅读Atomic Data文档了解Collections、Commits、JSON-AD等概念。

常见问题与故障排除

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

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