配置说明
本文列出 Olink 进程启动时读取的主要配置项:每一项是干什么的、默认值、以及怎么用环境变量 / TOML 改。改完一般需要 重启 Olink 才生效。
设备级「接入配置」(隐私 PIN、force_online 等)不在这里,见各设备 FAQ / 设备常离线问题。
配置从哪里来
启动时按顺序合并(后面覆盖前面):
- 环境变量(前缀
APP,嵌套用__) - 主配置文件(默认
data/config.toml;可用CFG_FILE改路径) {data_path}/application.toml(程序常自动生成,含instance_id;可手改其它[server]项)
旗舰等安装还会用 systemd 加载 {data_path}/.env,其中的 APP__… 会变成进程环境变量,再进入上面第 1 步。
等价写法示例(关闭 8123 监听):
| 方式 | 示例 |
|---|---|
| 环境变量 | APP__server__listen_8123=false |
config.toml / application.toml | [server] 下 listen_8123 = false |
| Docker | environment: - APP__server__listen_8123=false |
板子 .env | 写入 /opt/olink/data/.env 后 systemctl restart olink |
规则:APP + __ + 段名 + __ + 字段名。段名、字段名与 TOML 一致(如 server、listen_8123)。
另有一些 不走 APP__ 的独立环境变量(见文末)。
[server] 服务器
| 配置项 | 环境变量 | 默认 / 常见值 | 作用 |
|---|---|---|---|
listen | APP__server__listen | 如 0.0.0.0:5512 | HTTP 管理 / API 主监听地址(IP:端口)。浏览器打开控制台用这个端口。 |
data_path | APP__server__data_path | 如 data 或 /opt/olink/data、/data | 数据根目录:库、日志、.env、application.toml、备份等。 |
instance_id | APP__server__instance_id | 自动生成 UUID | 全局实例 ID(埋点、备份清单等)。通常由程序写入 application.toml 并同步到 .env,勿随意改。 |
management_server_host | APP__server__management_server_host | https://olinkd.hperfect.cn | 管理端 / 商业相关 HTTP 根地址(无尾斜杠)。空字符串会回落默认。 |
host_prefix | APP__server__host_prefix | olink | mDNS / 授权用主机名前缀。完整名一般为 {prefix}.homeassistant.local;冲突时自动变成 olink-2 等。 |
listen_8123 | APP__server__listen_8123 | true | 是否额外监听 8123(米家授权回调依赖 …:8123)。与本机 HA 冲突时可设 false,授权改手动粘贴。见 为何监听 / 接管 8123。主端口已是 8123 时不会再绑一次。 |
mdns_interfaces | APP__server__mdns_interfaces | 空 | mDNS 广告用的网卡名,逗号分隔(如 eth0,en0)。空 = 自动选第一个有全局 IPv4 的接口。多网卡 / Docker 绑错网卡时用这个纠正。 |
ble_discovery | APP__server__ble_discovery | true | 是否尝试 BLE 近场广播。无蓝牙适配器时基本为空操作;可关。 |
mdns_discovery | APP__server__mdns_discovery | true | 是否做 mDNS 侧发现相关逻辑。一般保持开启。 |
TOML 示例:
toml
[server]
listen = "0.0.0.0:5512"
data_path = "/opt/olink/data"
host_prefix = "olink"
listen_8123 = true
# mdns_interfaces = "eth0"
# ble_discovery = true
# mdns_discovery = true
# management_server_host = "https://olinkd.hperfect.cn"[database] 数据库
| 配置项 | 环境变量 | 默认 | 作用 |
|---|---|---|---|
url | APP__database__url | 未配置时用 {data_path}/db/data.db(SQLite) | 数据库连接串。SQLite 示例:sqlite:///opt/olink/data/db/data.db;也可接 PostgreSQL 等 SeaORM 支持的 URL。 |
toml
[database]
# url = "sqlite:///opt/olink/data/db/data.db"
# url = "postgres://user:password@localhost:5432/olink"不配则自动在 data_path 下建 SQLite,普通家用部署通常不用改。
[hap] HomeKit 绑定地址
| 配置项 | 环境变量 | 默认 | 作用 |
|---|---|---|---|
host | APP__hap__host | 空 = 自动取本机局域网 IP | HAP 桥接 / 配件对外宣告的 IP。多网卡时若家庭 App 连错地址,可写成明确 IPv4,如 "192.168.1.10"。 |
toml
[hap]
# host = "192.168.1.10"相关文件(非 APP__ 表内字段)
| 文件 | 典型路径 | 作用 |
|---|---|---|
log4rs.yaml | /opt/olink/log4rs.yaml(与 data 同级) | 日志级别与滚动文件。改 root.level 为 debug 后须重启。见 如何开启 Debug 日志。 |
.env | {data_path}/.env | 存放 APP__… 等,供 systemd EnvironmentFile 加载。 |
application.toml | {data_path}/application.toml | 常含 instance_id;也可写其它 [server] / [database] / [hap] 覆盖项。 |
config.toml | 默认 data/config.toml 或 CFG_FILE 指向处 | 主配置文件之一。 |
日志正文默认在 {data_path}/log/current.log。
其它常用环境变量
这些不是 Configs 结构体字段,但运维常见:
| 变量 | 作用 |
|---|---|
CFG_FILE | 主配置文件路径(默认相对路径 data/config.toml)。 |
JWT_SECRET | 控制台登录等 JWT 密钥;未设有内置默认,生产建议自设。 |
PLUGINS_DIR | JS 插件目录(默认 plugins)。 |
OTLP_ENDPOINT | OpenTelemetry 导出地址(可选)。 |
OLINK_ACTIVATE_KEY | 商业版等场景下的激活相关(以当前版本为准)。 |
RUST_BACKTRACE | 如 1,崩溃时打印 backtrace,便于排障。 |
DOCKER_CONTAINER | 标记运行在容器内(部分更新 / 路径逻辑会参考)。 |
摄像头硬编播种等还有 OLINK_FFMPEG_HW_* 一类变量,见摄像头 / Docker 硬编相关说明,不在本表展开。
改完怎么生效
- 改
.env/ toml / compose 环境变量后,重启 Olink(systemctl restart olink或重启容器)。 - 改
log4rs.yaml同样需要重启,见 如何开启 Debug 日志。 - 确认主端口:
ss -lntp | grep 5512(或你的listen端口);8123 是否监听取决于listen_8123。
相关文档
- 快速开始 — Compose 里常见的
APP__server__listen/data_path - 为何监听 / 接管 8123
- 如何开启 Debug 日志
- 米家授权后网络错误