Atomic Server 0.38.0 配置参数详解
Atomic Server 0.38.0 全部启动参数、ATOMIC_* 环境变量与 config.toml 凭据文件逐项详解:--help/show-config 全量实测回显、参数优先级、server_url 与 subject 一致性、search index 路径坑、public-mode 与 sled 存储层。
Atomic Server 0.38.0 配置参数详解
目标:逐项讲清 Atomic Server 0.38.0 的命令行参数、
ATOMIC_*环境变量、config.toml凭据文件与show-config生效值,覆盖端口/域名与 subject 一致性、HTTPS、路径与存储层、日志追踪等配置域。全部参数说明与回显基于 0.38.0 实机部署实测(2026-11-01,服务运行于 8139 端口,配置与数据目录指向部署目录/atomic-storage)。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 26.04.1 LTS |
| 服务版本 | atomic-server 0.38.0(--version 实测回显) |
| 服务入口 | atomic-server(cargo 安装名;官方发布仓库构建物入口为 /atomic-server-bin,本文回显保留其 Usage 原文) |
| 运行实例 | http://localhost:8139(ATOMIC_DOMAIN=localhost + ATOMIC_PORT=8139) |
| 配置目录 | /atomic-storage/config(ATOMIC_CONFIG_DIR) |
| 数据目录 | /atomic-storage/data(ATOMIC_DATA_DIR) |
| 生效配置查看 | atomic-server show-config(全文见 3.2) |
💡 说明:官方二进制默认
config_dir为~/.config/atomic/(--help原文),data_dir默认值随操作系统而定。本文实测环境通过环境变量把两者显式指向独立部署目录/atomic-storage,便于整目录备份——下文所有回显均出自该形态。
二、前置条件
- 已完成 Atomic Server 0.38.0 的安装与启动(部署步骤见 《Atomic Server Docker Compose 部署指南》);
- 服务以某个
ATOMIC_DOMAIN/ATOMIC_PORT组合运行,本文示例值localhost/8139; - 具备读取配置目录的权限(
config.toml含私钥,属敏感文件)。
三、参数查看与修改方式
3.1 四种配置来源与优先级
Atomic Server 的运行选项按「命令行 flag > 环境变量 > 内置默认值」生效。--help 为每个 flag 标注了对应的环境变量及当前实际取值,形如:
-p, --port <PORT>
The port where the HTTP app is available. ...
[env: ATOMIC_PORT=8139]
[default: 9883]
[env: ATOMIC_PORT=8139] 表示当前进程环境里该变量已设为 8139,[default: 9883] 是未设置时的出厂默认。环境变量清单可由 generate-dotenv 子命令生成模板(回显见 5.6 与部署篇)。
⚠️ 注意区分:
config.toml不是运行选项文件,而是首启生成的凭据文件(server/agent/private_key 三行,见 5.7)。修改端口等选项不要编辑它。
3.2 show-config:查看最终生效值
atomic-server show-config
0.38.0 实测全文回显(本实例 ATOMIC_DOMAIN=localhost、ATOMIC_PORT=8139):
Config {
server_url: "http://localhost:8139",
opts: Opts {
command: Some(
ShowConfig,
),
initialize: false,
rebuild_indexes: false,
development: false,
domain: "localhost",
port: 8139,
port_https: 9884,
ip: ::,
https: false,
https_dns: false,
email: None,
script: "",
config_dir: Some(
"/atomic-storage/config",
),
data_dir: Some(
"/atomic-storage/data",
),
public_mode: false,
server_url: None,
log_level: Info,
trace: Stdout,
slow_mode: false,
},
config_dir: "/atomic-storage/config",
key_path: "/atomic-storage/config/https/key.pem",
cert_path: "/atomic-storage/config/https/cert.pem",
https_path: "/atomic-storage/config/https",
config_file_path: "/atomic-storage/config/config.toml",
static_path: "/atomic-storage/data/static",
store_path: "/atomic-storage/data/store",
uploads_path: "/atomic-storage/data/uploads",
search_index_path: "/root/.cache/atomic-data/search_index",
initialize: false,
}
解读要点:顶层 server_url 由 domain+port 推导(server_url: None 表示未显式指定);key_path/cert_path/static_path/store_path/uploads_path 全部锚定在 config_dir/data_dir 之下;唯独 search_index_path 指向用户缓存目录 /root/.cache/atomic-data/search_index——这是本文最重要的坑(见 5.5)。
3.3 修改方式
- 命令行 flag:适合手工调试,如
atomic-server --port 8139 --log-level debug; - 环境变量:适合 systemd/编排托管,
Environment=ATOMIC_PORT=8139(每行一个变量)或.env文件; - 修改后需重启服务生效;涉及 subject 的变量(
ATOMIC_DOMAIN/ATOMIC_PORT/ATOMIC_SERVER_URL)变更后,历史数据的引用不会自动改写(见 5.1 ⚠️ 与 FAQ Q2)。
四、参数总览
atomic-server --help 实测全量回显(0.38.0,逐行照抄):
Create, share and model Atomic Data with this graph database server. Run atomic-server without any arguments to start the server. Use --help to learn about the options.
Usage: atomic-server-bin [OPTIONS] [COMMAND]
Commands:
export
Create and save a JSON-AD backup of the store
import
Import a JSON-AD file or stream to the store. By default creates Commits for all changes, maintaining version history. Use --force to allow importing other types of files
generate-dotenv
Creates a `.env` file in your current directory that shows various options that you can set
show-config
Returns the currently selected options, based on the passed flags and parsed environment variables
reset
Danger! Removes all data from the store
help
Print this message or the help of the given subcommand(s)
Options:
--initialize
Recreates the `/setup` Invite for creating a new Root User. Also re-runs various populate commands, and re-builds the index
[env: ATOMIC_INITIALIZE=]
--rebuild-indexes
Re-builds the indexes. Parses all the resources. Do this when updating requires it, or if you have issues with Collections / Queries / Search
[env: ATOMIC_REBUILD_INDEX=]
--development
Use staging environments for services like LetsEncrypt
[env: ATOMIC_DEVELOPMENT=]
--domain <DOMAIN>
The origin domain where the app is hosted, without the port and schema values
[env: ATOMIC_DOMAIN=localhost]
[default: localhost]
-p, --port <PORT>
The port where the HTTP app is available. Set to 80 if you want this to be available on the network
[env: ATOMIC_PORT=8139]
[default: 9883]
--port-https <PORT_HTTPS>
The port where the HTTPS app is available. Set to 443 if you want this to be available on the network
[env: ATOMIC_PORT_HTTPS=]
[default: 9884]
--ip <IP>
The IP address of the server. Set to :: if you want this to be available to other devices on your network
[env: ATOMIC_IP=]
[default: ::]
--https
Use HTTPS instead of HTTP. Will get certificates from LetsEncrypt fully automated
[env: ATOMIC_HTTPS=]
--https-dns
Initializes DNS-01 challenge for LetsEncrypt. Use this if you want to use subdomains
[env: ATOMIC_HTTPS_DNS=]
--email <EMAIL>
The contact mail address for Let's Encrypt HTTPS setup
[env: ATOMIC_EMAIL=]
--script <SCRIPT>
Custom JS script to include in the body of the HTML template
[env: ATOMIC_SCRIPT=]
[default: ]
--config-dir <CONFIG_DIR>
Path for atomic data config directory. Defaults to "~/.config/atomic/""
[env: ATOMIC_CONFIG_DIR=/atomic-storage/config]
--data-dir <DATA_DIR>
Path for atomic data store folder. Contains your Store, uploaded files and more. Default value depends on your OS
[env: ATOMIC_DATA_DIR=/atomic-storage/data]
--public-mode
CAUTION: Skip authentication checks, making all data publicly readable. Improves performance
[env: ATOMIC_PUBLIC_MODE=]
--server-url <SERVER_URL>
The full URL of the server. It should resolve to the home page. Set this if you use an external server or tunnel, instead of directly exposing atomic-server. If you leave this out, it will be generated from `domain`, `port` and `http` / `https`
[env: ATOMIC_SERVER_URL=]
--log-level <LOG_LEVEL>
How much logs you want. Also influences what is sent to your trace service, if you've set one (e.g. OpenTelemetry)
[env: RUST_LOG=]
[default: info]
[possible values: warn, info, debug, trace]
--trace <TRACE>
How you want to trace what's going on with the server. Useful for monitoring performance and errors in production. Combine with `log_level` to get more or less data (`trace` is the most verbose)
[env: ATOMIC_TRACING=]
[default: stdout]
Possible values:
- stdout:
Log to STDOUT in your terminal
- chrome:
Create a file in the current directory with tracing data, that can be opened with the chrome://tracing/ URL
- opentelemetry:
Log to a local OpenTelemetry service (e.g. Jaeger), using default ports
--slow-mode
Introduces random delays in the server, to simulate a slow connection. Useful for testing
[env: ATOMIC_SLOW_MODE=]
-h, --help
Print help information (use `-h` for a summary)
-V, --version
Print version information
⚠️ 注意:
--help中[env: ATOMIC_PORT=8139]、[env: ATOMIC_CONFIG_DIR=/atomic-storage/config]等方括号行反映的是当前进程环境变量实值(本实例设过),并非出厂默认;出厂默认看紧随其后的[default: ...]行。
五、核心参数分类详解
5.1 域名与端口(subject 生成三要素)
| 参数 | 环境变量 | 默认 | 实测说明 |
|---|---|---|---|
--domain | ATOMIC_DOMAIN | localhost | 对外主机名,不含协议与端口 |
-p, --port | ATOMIC_PORT | 9883 | HTTP 监听端口;show-config 实测本实例为 8139 |
--port-https | ATOMIC_PORT_HTTPS | 9884 | HTTPS 监听端口 |
--ip | ATOMIC_IP | :: | 监听地址,:: 为双栈全接口 |
--server-url | ATOMIC_SERVER_URL | 空(自动推导) | 经反向代理/隧道时显式指定完整 URL |
这三者共同决定 server_url(实测 http://localhost:8139),而 server_url 又决定所有本地资源 subject 的前缀:首启日志 Setting rights to Drive http://localhost:8139 表明根 Drive 的 subject 就是 server_url 本身;资源如 http://localhost:8139/mood/1、Agent 如 http://localhost:8139/agents/uuIgCqY79Wq1ZLU7y1tHIisGWmdSkHC2oAsGaioFANg= 全部以其为前缀(API 篇有逐条实测)。
⚠️ 注意:server_url 在首次建库时固化进数据。事后改端口/域名,旧资源 subject 不会重写,集合与链接将指向旧地址(表现为页面 404、数据「消失」)。正确姿势:部署前定好最终 URL;确需变更则属数据迁移范畴(需改写 subject,import/export 不具备该能力,见部署篇 9.4 实测结论)。
5.2 HTTPS 与证书自动化
| 参数 | 环境变量 | 说明(help 原文要点) |
|---|---|---|
--https | ATOMIC_HTTPS | 启用 HTTPS,证书全自动向 LetsEncrypt 申请 |
--https-dns | ATOMIC_HTTPS_DNS | 用 DNS-01 质询签发(子域名场景) |
--email | ATOMIC_EMAIL | LetsEncrypt 联系邮箱 |
--development | ATOMIC_DEVELOPMENT | 切换 LetsEncrypt staging 环境(避免测试期触发生产速率限制) |
证书落点由 show-config 实测确认:https_path: "/atomic-storage/config/https"、key_path: "/atomic-storage/config/https/key.pem"、cert_path: "/atomic-storage/config/https/cert.pem"。若 TLS 终结在外部反向代理(如 Nginx),则不开 --https,改为设置 ATOMIC_SERVER_URL=https://实际域名 保证 subject 正确。
5.3 路径与存储层(sled)
| 参数 | 环境变量 | 默认 | 实测生效值 |
|---|---|---|---|
--config-dir | ATOMIC_CONFIG_DIR | ~/.config/atomic/ | /atomic-storage/config |
--data-dir | ATOMIC_DATA_DIR | 随 OS | /atomic-storage/data |
show-config 给出的派生路径:config_file_path(config.toml)、static_path(data/static)、store_path(data/store)、uploads_path(data/uploads)。store 目录实测结构(首启后):
/atomic-storage/data/store
/atomic-storage/data/store/blobs
/atomic-storage/data/store/conf
/atomic-storage/data/store/db
/atomic-storage/data/store/snap.000000000081ADA0
存储引擎为 sled 嵌入式 KV:db 为段文件区、snap.* 为检查点快照、blobs/conf 为元数据。实测空库+核心本体约 2.5M(du -sh 输出 2.5M /atomic-storage/data/store)。
💡 技术拓展:sled 属于「嵌入式存储引擎」家族,常见同类对比——
引擎 形态 特点 代表软件 sled Rust 嵌入式 LSM 无外部服务、进程内锁单实例 Atomic Server RocksDB C++ 嵌入式 LSM 生态最广、调优项多 TiKV、CockroachDB LMDB B+ 树 mmap 读极快、单写者 OpenLDAP、libp2p 节点 SQLite 单文件关系库 通用、WAL 并发 各类 App sled 的「进程内文件锁」正是运行中执行 CLI 备份报
could not acquire lock的根因(5.6 实测),运维时必须停服或走单写者路径。
5.4 行为开关
| 参数 | 环境变量 | 说明 |
|---|---|---|
--initialize | ATOMIC_INITIALIZE | 重建 /setup 邀请、重跑 populate 并重建索引(help 原文);忘记根凭据/邀请用尽后的恢复入口 |
--rebuild-indexes | ATOMIC_REBUILD_INDEX | 全量解析资源重建索引;升级要求或 Collections/查询/搜索异常时使用 |
--public-mode | ATOMIC_PUBLIC_MODE | 跳过鉴权检查、全部数据公开可读、提升性能(help 原文 CAUTION) |
--slow-mode | ATOMIC_SLOW_MODE | 注入随机延迟模拟慢网络,测试用 |
--script | ATOMIC_SCRIPT | 向 HTML 模板注入自定义 JS(默认空串) |
public_mode 实测默认 false。注意 0.38 的默认读权限本就是开放的(匿名 GET 资源返回 200,API 篇实测),--public-mode 的增量是跳过鉴权检查换性能,代价是层级权限完全失效——多租户/私有数据场景严禁开启。
5.5 检索索引路径(重要坑位)
show-config 实测 search_index_path: "/root/.cache/atomic-data/search_index"——索引不随 --data-dir 走,而是落在运行用户的缓存目录。后果与对策(均实测):
- 数据目录整体备份/迁移时索引不在其中;全新库首启会自动建索引(首启日志
Adding all resources to search index→Building search index...→Search index finished!,本例约 4 秒); - 但库中已有数据而索引目录缺失时,启动不会自动重建(实测:服务实例重建后重启,日志仅有
Starting search service,/search?q=Mood返回 0 条而直读资源正常;此后只有新提交被增量索引,存量资源不回索引); - 若怀疑索引与库不一致或索引已丢,用
--rebuild-indexes(或环境变量ATOMIC_REBUILD_INDEX=true)启动一次强制全量重建:日志Removing existing search index...→Building search index...→Search index finished!,完成后搜索即恢复全量(实测q=Mood由 0 回到 4 条); - 生产部署建议把该路径纳入持久化与备份清单;否则每次重建实例都需手动跑一次
--rebuild-indexes才能恢复搜索。
5.6 CLI 子命令与配置的关系
export/import/reset/generate-dotenv/show-config 五个子命令(help Commands 段原文)共享同一套 flag/环境变量解析——即它们也按 ATOMIC_CONFIG_DIR/ATOMIC_DATA_DIR 定位库文件。实测两处细节:
generate-dotenv在当前目录生成全量注释模板,成功回显Successfully created /work/.env;已有.env时 panic(实测回显):
thread 'main' panicked at server/src/bin.rs:118:17:
/work/.env already exists
reset需要 TTY 交互确认,非交互执行 panic(实测回显):
thread 'main' panicked at server/src/bin.rs:100:14:
called `Result::unwrap()` on an `Err` value: IO(Custom { kind: NotConnected, error: "not a terminal" })
各子命令参数(export -p/--only-internal、import --file/--parent/--force)与完整备份恢复流程见部署篇第九章。
5.7 config.toml 凭据文件
首启自动生成,实测全文:
server = "http://localhost:8139"
agent = "http://localhost:8139/agents/uuIgCqY79Wq1tHIisGWmdSkHC2oAsGaioFANg="
private_key = "aKyy/8Ij6aOibh6LhozEweJELzmo6seGLjxtFBQaw5U="
server:本服务器根 URL(= server_url,也是根 Drive subject);agent:默认根 Agent 的资源 URL(公钥身份);private_key:根 Agent 签名私钥(Base64 Ed25519)。
它是凭据而非配置项:客户端用它签名写入(API 篇演示),改端口等选项无效。首启日志 WARN 原文即提示「Copy this to your client machine (running atomic-cli or atomic-data-browser) to log in with these credentials」。丢失该文件且无备份时,可用 --initialize 重建 /setup 邀请重新注册管理 Agent(但旧 Agent 签名链的归属权无法找回)。
六、生产配置模板
以下为「公网域名 + HTTPS + 独立数据盘」场景的托管形态示例(systemd unit 的 [Service] 段环境变量注入方式;内存占用为 Rust 单进程,实测 6 worker 线程,1GB 内存 VPS 即可承载个人/小团队规模;数据盘建议 SSD 以匹配 sled 的 LSM 写放大):
[Service]
Environment=ATOMIC_DOMAIN=notes.example.com
Environment=ATOMIC_PORT=8139
Environment=ATOMIC_HTTPS=
Environment=ATOMIC_EMAIL=ops@example.com
Environment=ATOMIC_CONFIG_DIR=/srv/atomic/config
Environment=ATOMIC_DATA_DIR=/srv/atomic/data
Environment=RUST_LOG=info
Environment=ATOMIC_TRACING=stdout
ExecStart=/usr/local/bin/atomic-server
Restart=unless-stopped
逐项说明:ATOMIC_DOMAIN + ATOMIC_PORT 决定 subject 前缀,上线前必须定死(5.1);ATOMIC_HTTPS 与 ATOMIC_EMAIL 启用 LetsEncrypt 自动证书(5.2),若 TLS 由前置 Nginx 终结则不开 --https 并改设 ATOMIC_SERVER_URL=https://notes.example.com;ATOMIC_CONFIG_DIR/ATOMIC_DATA_DIR 指向数据盘挂载点,配合 crontab 停服 export 做备份(部署篇 9.3);不开 ATOMIC_PUBLIC_MODE(5.4)。
七、常见问题
Q1:改了 ATOMIC_PORT 重启后,页面数据看不到了?
历史资源 subject 仍指向旧端口 URL(5.1)。端口即身份:要么改回,要么用新库重新初始化(--initialize 会重建邀请与索引,但不改写旧数据 subject)。
Q2:config.toml 里改 server 值能换域名吗?
不能。运行选项只认 flag/环境变量;config.toml 是凭据记录,手改会造成客户端凭据与服务器实际 server_url 不一致。
Q3:搜索结果与集合查询时有时无?
先跑 --rebuild-indexes(help 原文即针对 "issues with Collections / Queries / Search")。另注意 0.38 实测:自定义属性值默认不进全文索引(API 篇 Search 节有 q=stormy 0 结果的对照实验),属索引口径而非故障。
Q4:show-config 里 port: 9883 和部署文档的 8139 对不上?
show-config 反映当前进程的生效值。未设 ATOMIC_PORT 时出厂默认就是 9883(help [default: 9883]);托管环境请核对 unit/编排文件的环境注入。
Q5:--trace 生产怎么配?
默认 stdout。需要接入监控时选 opentelemetry(本地上报 Jaeger 默认端口),排障期可临时 chrome 生成本地追踪文件用 chrome://tracing/ 打开;配合 RUST_LOG=trace 获取最详细数据(help 原文建议)。
Q6:想彻底清库重来?
交互终端执行 reset 子命令(需 TTY 确认,panic 原文见 5.6),或整目录删除 config_dir/data_dir 内容后重启——首启日志会重新走 Initialize: creating and populating new Database 全流程(部署篇 4.5)。
八、参考链接
- 官方文档站:https://docs.atomicdata.dev (配置与安装章节)
- GitHub 仓库:https://github.com/ontola/atomic-server
- 官方文档站 AtomicServer 配置页:https://docs.atomicdata.dev/atomicserver/configuration.html
- sled 存储引擎:https://github.com/spacejam/sled
- 站内互链:《Atomic Server 介绍与选型指南》、《Atomic Server Docker Compose 部署指南》