数据后端
IronFlock 为每个项目配置一个由 TimescaleDB 驱动的私有数据库。您的应用定义数据模式;IronFlock 在设备加入应用的那一刻就创建表并开始采集数据。
工作原理
- 在
.ironflock/data-template.yml中定义数据模式。 - 使用 IronFlock SDK 从边缘代码发布数据。
- IronFlock 在安装该应用的每个项目中自动创建数据库表。
- 数据从设备通过消息系统流入项目数据库。
每个项目都有自己的物理数据库——项目之间不共享数据。
用户对其项目中由您的应用采集的数据拥有完全控制权。作为开发者,您无法访问这些数据。
定义数据模式
在 .ironflock/ 目录中创建 data-template.yml 文件:
data:
tables:
- tablename: sensordata
columns:
- id: tsp
name: Timestamp
description: Timestamp of measurement
path: args[0].timestamp
dataType: timestamp
- id: temperature
name: Temperature
description: Temperature reading in Celsius
path: args[0].temperature
dataType: numeric
- id: humidity
name: Humidity
description: Relative humidity percentage
path: args[0].humidity
dataType: numeric
- id: device_id
name: Device ID
description: Source device identifier
path: args[0].device_id
dataType: string列选项
| 字段 | 描述 |
|---|---|
id | 内部列标识符(时间戳列使用 tsp) |
name | 人类可读的列名,显示在仪表板中 |
description | 可选描述 |
path | 发布的数据对象中值的路径(例如 args[0].temperature) |
dataType | 可选值:timestamp、numeric、string、boolean |
secret | 将该列加密存储,普通读取永远不会以明文返回——参见下文机密列 |
机密列
有些值必须存储下来,却绝不能被展示出来:API 令牌、设备密码、许可证密钥。把该列标记为 secret: true,数据后端就会在插入时对它加密:
- tablename: credentials
columns:
- id: tsp
dataType: timestamp
- id: device_id
dataType: string
- id: api_token
dataType: string
secret: true从此没有任何普通读取会返回明文——即使是写入它的那个应用也不例外:
| 读取路径 | 你得到的内容 |
|---|---|
| 历史读取和实时行:仪表板、组件、SDK 以及读取该表的其他应用所得到的内容 | 占位符 __secret__ |
| SQL(SQL 查询控制台、数据导出以及 FleetDB Access 的 Postgres 登录)和数据库备份 | 存储的密文,ifsec:1:… |
| SDK 的明文读取函数 | 解密后的值 |
NULL 在所有路径上都保持为 NULL,因此“已设置但被隐藏”与“从未写入”依然可以区分。
只有从应用自己的容器中、通过 SDK 才可能以明文读回机密值——参见 SDK 参考中的机密列。仪表板和其他应用完全无法获取它,正是这一点让“绝不以明文展示”成为事实,而不只是表面功夫。
在不丢失机密值的前提下更新行。 在实体表上,编辑某行的客户端永远无法把真正的机密值发回来——读取时它拿到的只有占位符。因此,数据后端在写入时会把占位符 __secret__(以及仪表板显示的掩码 ••••••••)视为保留原有值,省略机密列同样会保留原有值。显式发送 null 则会清除机密值。因此,在仪表板表单中编辑一台机器的描述,绝不会抹掉它的访问码。
由此产生两个后果:字面字符串 __secret__ 和 •••••••• 本身无法作为机密值存储(原始的 ifsec:… 密文作为输入也会被拒绝);而在没有实体键的表上,写入占位符会被拒绝——因为不存在可以保留的前一行。
有三点后果值得在设计时就考虑进去,因为它们是硬性限制,而非建议:
- 机密列只能是字符串。 加密的产物是文本,因此
numeric、boolean和timestamp列不能设为机密列。必需的tsp列同样不能设为机密列。 - 你不能按机密列过滤、分组或排序。 每一行都用它自己的随机值加密,因此两行持有相同的机密值时,存储的是不同的密文。对机密列使用等值过滤、
GROUP BY、ORDER BY和DISTINCT根本无法工作。要回答“这个值是否匹配?”,请使用 SDK 的校验函数——它在数据后端内部完成比较,而不返回任何内容。 - 机密列不能作为实体键。 由于每一行的密文都不相同,按实体取最新行的读取会把每一行都当成一个独立的实体,因此在
maintainLatestFlagFor中指定机密列会被直接拒绝。
后两条限制会在数据模板通过校验时被检查,因此违反它们的表会在发布时失败,而不是之后才出现异常行为。
表选项
除了 columns 之外,表还接受若干可选键,用于控制表的描述方式以及数据的留存时长:
data:
tables:
- tablename: sensordata
description: 车间的环境测量数据
chunkTimeInterval: 1 hour
dropAfter: 30 days
columns:
# ...| 字段 | 描述 |
|---|---|
tablename | 表名 |
description | 可选描述,显示在界面中,并供 AI 智能体理解该表 |
chunkTimeInterval | 表被切分成的时间分区大小。默认为 7 days |
dropAfter | 保留窗口——早于该区间的分区会被自动删除 |
downsample | 维护一份预聚合副本,用于快速绘制长窗口图表——参见下文持续降采样 |
maintainLatestFlagFor | 标识唯一实体的列——参见下文跟踪实体的最新状态 |
private | 对其他应用隐藏该表——参见下文与其他应用共享数据 |
chunkTimeInterval 决定时序数据在磁盘上的分区方式。请选择让单个分区大致对应一次查询数据量的值:每秒采集的高频数据适合较小的分块(分钟到小时),变化缓慢的数据则适合较大的分块(周)。这只是应用的默认值——项目所有者之后可以在自己的数据后端中调整。
dropAfter 会把表变成一个滚动窗口。早于所给区间的分区会被整块删除,这远比逐行删除便宜。清理任务按 dropAfter / 4 的周期运行,因此一条记录在其分区被移除之前,最多可能超出有效期该区间的四分之一。省略 dropAfter 即可无限期保留数据。
两者都接受 PostgreSQL 的区间字符串——30 minutes、1 hour、7 days、6 months。
持续降采样
仪表板可以要求数据库聚合数据——每小时平均值、每天合计、每台机器的计数。用原始记录来计算这些,跨一天没问题,跨一年就代价高昂。为表添加 downsample,平台就会为它维护一份持续更新的预聚合副本,并改用该副本回答长窗口查询:
data:
tables:
- tablename: sensordata
dropAfter: 30 days
downsample:
bucket: 1 minute
keepFor: 2 years
paths:
- payload.temperature
columns:
# ...| 字段 | 描述 |
|---|---|
bucket | 预聚合副本的粒度。默认为 1 minute |
keepFor | 降采样历史的保留时长。省略则无限期保留 |
paths | 要纳入的 JSON 字段路径,采用与仪表板相同的表示法 |
bucket 是图表能够从该副本获取的最细分辨率——若图表请求的时间桶远细于此值,则改为读取原始表。它接受从 1 second 到 1 day 之间能整除一天的固定宽度区间(1 minute、5 minutes、1 hour)。默认的 1 minute 几乎适用于所有仪表板;更粗的桶占用更少存储、也带来更小的写入吞吐开销。
keepFor 才是让长历史数据成为可能的关键。原始记录会随 dropAfter 消失,而降采样副本有自己的保留期:原始数据保留 30 天、降采样数据保留 2 年,看板便仍可用极小的存储代价绘制两年的每小时平均值。请把它设得比 dropAfter 更长——相反的配置会被平台判定为错误配置并拒绝。
paths 把降采样扩展到 JSON 列内部的值。数值列会自动纳入;而 JSON 字段必须显式指定,因为 JSON 列没有固定的键集合。未声明的字段在仪表板中仍然可用——只是改为从原始表计算。
其余一切都是自动的。每个数值列都会维护其统计量(平均值、总和、最小值、最大值、第一个值、最后一个值以及记录条数),并按表的实体键(maintainLatestFlagFor,或发布数据的设备)分组。仪表板无需任何配置,也无需知晓其存在:小部件照常查询,平台会针对每次查询判断预聚合副本能否作答——不能时便透明地回退到原始表,例如当某个过滤条件引用了副本未按其分组的列时。
模式变更会重建副本。 为降采样表添加、删除或更改列的类型——或编辑
downsample块本身——都会从原始表重建预聚合副本。任何早于dropAfter的数据都无法重建,将会丢失。请尽可能在建表时就一并配置该块,并把长期存在的表上的后续模式变更视为一项需要慎重权衡的决定。
从边缘代码发布数据
使用 IronFlock SDK 从应用发送数据:
Python
from ironflock import IronFlock
flock = IronFlock()
await flock.start()
await flock.publish_to_table("sensordata", {
"timestamp": "2025-01-15T10:30:00Z",
"temperature": 23.5,
"humidity": 62.1,
"device_id": "sensor-001"
})每一行都需要为必需的 tsp 列提供一个值:数据后端会拒绝缺少该值的行。SDK 的表写入会以错误失败;看板发布的行则会被丢弃,只在应用的 error-logs 表中留下一条记录。上面 sensordata 的定义用 path: args[0].timestamp 映射该列,因此 tsp 取自行的 timestamp 字段。没有 path 的列读取行中同名的字段(args[0].<id>):如果没有这一映射,每一行都需要自带一个 tsp 字段。
对于高频数据,请使用 publish_rows_to_table / publishRowsToTable / PublishRowsToTable 或 append_rows_to_table / appendRowsToTable / AppendRowsToTable 在单条消息中发送多行,而非每行进行一次往返通信——两者相同,都会报告插入结果。每个批次都会原子地插入——全部成功或全部失败。详情请参阅 SDK 参考。
转换表
您可以定义 SQL 转换,自动对原始数据进行聚合或处理:
data:
tables:
- tablename: sensordata
columns:
# ... 原始数据列 ...
transforms:
- tablename: hourly_averages
materialize: true
schedule: "0 * * * *"
sql: >
SELECT
time_bucket('1 hour', tsp) AS hour,
avg(temperature) AS avg_temp,
avg(humidity) AS avg_humidity
FROM sensordata
GROUP BY hour
columns:
- id: hour
name: Hour
dataType: timestamp
- id: avg_temp
name: Average Temperature
dataType: numeric
- id: avg_humidity
name: Average Humidity
dataType: numeric| 字段 | 描述 |
|---|---|
tablename | 派生表的名称 |
materialize | 若为 true,结果会被存储,并按计划刷新。若为 false,转换是一个视图,每次读取时计算 |
schedule | 转换运行的 Cron 表达式:5 个字段(分钟、小时、日、月、星期),或在开头加一个秒字段,共 6 个字段。*/5 * * * * 每 5 分钟运行一次,*/10 * * * * * 每 10 秒运行一次。每次运行都会刷新物化结果,并将当前结果发送到绑定该转换的看板。应用的代码也可以按需触发这样的一次运行,参见按需刷新 |
sql | 计算转换的 SQL 查询 |
columns | 输出的列定义 |
转换表可以在仪表板和 SDK 中访问,与常规表的使用方式完全相同。
读取转换时,返回的正是其自身 SQL 所给出的结果:小部件的时间窗口、日历过滤器以及 latest 模式适用于表,对转换则会被忽略。由此引出三条规则。在查询内部限定时间范围(WHERE tsp > now() - interval '7 days');让时间序列按从新到旧排序(ORDER BY <时间列> DESC),以便行数上限保留最新的行;并选出看板需要绘制或过滤的每一列——转换没有隐含的时间戳列或设备列。单次读取最多返回 3000 行,因此请在查询中聚合。
转换用于表读取无法表达的内容:连接、比率、对多个表当前行的聚合。它不是用来显示实体当前状态或隐藏已删除记录的方式。那些是表自身的读取模式——latest 开关和针对 deleted 列的过滤器(见下文)——并且实时生效:绑定到表的小部件会在一秒内跟上每一条新行。转换只会按其计划到达看板(或者在应用的代码于自身写入之后刷新它时——看板的保存绝不会触发这一点),因此一个选出每个实体最新行或丢弃已删除行的视图,只是把同样的结果延后显示。当转换确实需要实体表的当前状态时,例如要与另一个表连接,请在其 SQL 中用 DISTINCT ON 选出该状态,并在那里应用 deleted 检查,顺序如软删除记录所示。
随应用一起发布转换并不是获得转换的唯一途径:拥有数据访问权限的项目成员可以在项目的数据视图中保存同样的转换,无需任何应用,AI 助手同样可以。参见自定义转换。
物化转换何时刷新
只有当物化转换读取的某个表自上次刷新以来被写入过时,计划运行才会刷新它;除此之外,无论如何至少每 10 分钟刷新一次。没有新内容可读的运行会让存储的结果保持不变:一个按每分钟计划运行、所读的表每小时只收到一行的转换,会在这一行写入后刷新,其余时间每 10 分钟刷新一次。
当物化转换的结果无需写入也可能变化时,它会在每次运行时刷新:
- 其 SQL 使用当前时间或随机数,例如
now()、CURRENT_DATE或random(); - 它调用了对相同输入可能返回不同结果的函数:易变(volatile)函数,或非 PostgreSQL 内置的稳定(stable)函数;
- 它读取了应用表和物化转换以外的内容,例如非物化转换、降采样副本或平台自身的某个表。
当许多转换在同一时刻到期时,平台每次只刷新其中几个,其余的排队等待,因此刷新可能晚于计划的时间才完成。如果某次运行到期时,同一转换的上一次刷新仍在运行或等待中,这次运行会被跳过。
按需刷新
应用自己的代码可以不等计划就触发转换的一次运行:SDK 的 refresh_transform / refreshTransform / RefreshTransform 会刷新物化结果(普通视图只会被读取),并将当前结果发送到绑定该转换的看板,因此看板会立刻显示应用刚刚写入的一批数据。它遵循与计划运行相同的规则:如果转换读取的表自上次刷新以来都没有被写入,这次刷新会被跳过——并报告为已跳过;在同一转换的刷新仍在运行时到达的调用,会等待排在其后的那一次刷新;每个转换每秒最多启动一次刷新。SDK 的表写入在返回前已经提交,因此先写入再刷新绝不会漏掉这次写入。只有应用自己的容器才能刷新它的转换;看板只接收行,而消费另一个应用数据的应用可以读取其转换,但不能刷新它们。从项目数据视图保存的转换不属于任何应用,只按其计划运行。参见 refreshTransform / refresh_transform / RefreshTransform。
跟踪实体的最新状态
对于表示真实世界实体(机器、资产、生产订单)当前状态的表,IronFlock 支持一种名为最新状态跟踪的模式。
当数据发生变化时,您不是覆盖原有行,而是始终追加新行。您声明哪些列用于标识一个唯一实体,IronFlock 会在每次读取该表时推导出每个实体的最新行。这让您既能保留每次变更的完整历史,又能轻松查询当前状态。
通过 maintainLatestFlagFor 在表上启用此功能:
- tablename: machineform
maintainLatestFlagFor: ['machinename']
columns:
- id: tsp
dataType: timestamp
- id: machinename
dataType: string
- id: machinetype
dataType: string
- id: active
dataType: boolean
- id: description
dataType: stringmaintainLatestFlagFor 接受一组列,这些列组合起来标识一个唯一实体。行本身不会被写入任何额外内容:IronFlock 会按该实体键加时间戳为表建立索引,并在查询时选出每个实体的最新行。因此,迟到或乱序到达的行绝不会遗留下过时的标记。
实体表中每个实体在每个时间戳上只有一行。与已存储行的实体键和 tsp 都相同的行会被拒绝,其中有两行彼此如此重复的批次同样会被拒绝:SDK 的写入以 URI_ENTITY_KEY_CONFLICT 失败,应用的 error-logs 表会记录这次拒绝。请为实体的每个版本使用各自的 tsp。实体键列为空(NULL)的行不属于任何实体:它永远不会因重复而被拒绝,最新状态读取也会将其排除在外。
用部分行更新实体
追加到实体表的每一行都是该实体的一个新版本——而且它不必是完整的。行中未提供的列会从该实体此前的最新行继承,因此更新单个字段只需发布实体键、时间戳和该字段本身:
| 新行中的该列 | 存储的版本中保存的是 |
|---|---|
已提供(0、false 和 "" 均算作已提供) | 所提供的值 |
显式为 null | NULL——该列被清空 |
| 缺失 | 此前最新行中的值 |
要清空某列,请将其作为 null 发送(Python 中为 None,Go 中为 nil,C# 中为 null)。省略该列则会保留之前的值。请留意那些无意中省略字段的代码:例如,值为 undefined 的 JavaScript 属性会从负载中被丢弃。SDK 参考按语言列出了这些情况。
有两个细节值得了解:
- 提供了所有列的行会完全跳过对前一行的查找,因此完整行的开销与以往完全相同——在高频路径上请继续发送完整行。
- 继承遵循时间顺序:带着较早时间戳到达的行(即回填)只会从时间戳等于或早于其自身
tsp的行继承,绝不会从更新的行继承。
没有 maintainLatestFlagFor 的表保持普通的追加语义:行中未提供的列会被存储为 NULL。
仅查询当前机器状态:
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC查看特定机器的完整历史:
SELECT * FROM machineform WHERE machinename = 'Assembly-Line-01' ORDER BY tsp您很少需要手写这条查询,也不应把它存成转换。连接到此表的仪表板组件在其过滤设置中提供 latest 开关,因此用户无需任何额外操作即可始终看到当前值。这个开关是实时的:组件会在表的每一条新行到达时收到它,并用它替换该实体之前的那一行,因此变更在写入后一秒内就会显示,而表仍保留每一个版本。没有任何内容按计划重新计算——而这正是转换唯一会增加的东西。在 SDK 中,只需向 filterAnd 添加 {"latest": true} 即可请求同样的模式——参见 getHistory。
从
latest_flag升级: IronFlock 的早期版本会存储一个名为latest_flag的物理布尔列。该列已不再存在——当前状态改为在 SQL 中推导得出,这样即使行乱序到达也能保持正确。现有的仪表板和按latest_flag = true过滤的 SDK 调用仍可继续工作:IronFlock 会识别它们并应用最新状态模式。新代码应使用 latest 开关或{"latest": true}过滤条目。
更改实体键
应用版本一旦发布,其每个表的实体键就固定下来。对于应用最新发布版本中已有的表,如果 data-template.yml 更改了它的实体键,云端 IDE 侧面板中的更新数据结构和新版本发布的构建都会拒绝该文件:
- 向
maintainLatestFlagFor添加列、从中删除列、替换列或更改列的顺序; - 为原本没有
maintainLatestFlagFor的表添加它,或将其删除。
这样的更改会悄无声息地改变该表在每个安装了此应用的项目中返回的内容。新加入键的列在每一条现有行中都为空,而最新状态读取会排除键列为空的行,因此所有现有实体都会消失。从键中移除一列,可能使行具有相同时间戳的多个实体合并,而该表每个实体每个时间戳只能容纳一行。
要使用不同的实体键,请用新键创建一个新表,并把数据迁移过去,例如从应用的代码中迁移。数据迁移由应用负责。尚未包含在任何发布版本中的表,在开发期间仍可更改其实体键。在此规则生效之前发布的应用版本仍可以更改实体键:更新到该版本的项目会拒绝这次数据结构更新,并保留之前的数据结构。
实体与时间戳重复的行
在 IronFlock 强制每个实体每个时间戳只有一行之前写入的表,仍可能包含重复行;更改过实体键的开发表也是如此。当数据服务设置这样的表时(在其启动时或数据结构更新之后),它会把每个重复组的所有行移到同一数据后端中名为 <table>__entitykey_dupes 的表,并把每组中的一行放回原表。此后,该表会拒绝重复行。应用的 error-logs 表中会有一条记录说明移动了多少行。
新表按原样保留每一条被移动的行,并增加两列:quarantined_at 表示移动的时间,restored 标记被放回的那一行。放回哪一行是任意的,这与最新状态读取原本的情况一样。可在项目数据视图的查询控制台中以 databackend_<key>.<table>__entitykey_dupes 查询它。如果原表是私有的,新表也是私有的。如果这些行无法移动,error-logs 中的记录会说明原因,数据服务会在下次启动时重试。
软删除记录
IronFlock 的仅追加模型意味着记录永远不会被物理删除。取而代之的是,使用 deleted 布尔列将记录标记为已删除。这在从仪表板中隐藏已删除记录的同时,保留了完整的审计跟踪。
在任何实体表中添加 deleted 列:
- id: deleted
name: Deleted
dataType: boolean当用户删除一条记录(例如通过仪表板上的表单),您的应用会为该实体发布一个 deleted: true 的新行。结合 maintainLatestFlagFor,这个新行将成为最新状态。之后的部分行会像继承其他任何列一样继承 deleted 标记,因此未提及 deleted 的更新既不会让该实体复活,也不会把它隐藏起来。
仅查询活跃(未删除)的当前记录:
SELECT * FROM (
SELECT DISTINCT ON (machinename) *
FROM machineform
ORDER BY machinename, tsp DESC
) latest
WHERE deleted IS NULL OR deleted = falsedeleted 检查是在选出每台机器的最新行之后才执行的。这个顺序很重要:如果先过滤掉已删除的行,前一行未删除的记录就会重新浮现,成为当前状态。
仪表板组件和 SDK 会自动应用相同的顺序——将 latest 开关(或 {"latest": true})与 deleted 过滤条件结合使用,就能得到完全一致的行为。已删除的记录在表单提交后会立即从面板中消失,但仍保留在数据库中,用于历史记录和审计目的。
在仪表板上,由删除表单删除记录:删除表单是提交按钮显示 删除、并由隐藏的复选框字段将 true 连同记录的键一起写入 deleted 列的表单(参见删除数据)。列出这些记录的组件过滤的是表本身。无需任何视图或转换来清理列表,而且即便有,它也只会在下一次计划运行时才显示出删除。
与其他应用共享数据
数据后端仅属于你的应用:项目中安装的其他应用都看不到你的表。data-template.yml 中的两个可选键可以改变这一点。
要读取其他应用的数据,请在顶层的 consumes: 部分列出想要读取的应用——它与 data: 平级,而不是嵌在其中:
consumes:
- app: machine-monitor
reason: "根据该监控应用的机器状态和计数器数据流计算 OEE"
data:
tables:
- tablename: oee_results
columns:
# ... 照常定义你自己应用的表app 是提供方应用的技术名称,或用 "*"(引号是必需的)表示项目中的所有应用。reason 会在授权对话框中展示给用户——仅有声明本身不会授予任何权限,必须由用户批准。
要保留某些表不共享,将其标记为 private: true。你定义的内容默认都是可共享的;私有的表或转换根本不会出现在其他应用看到的目录中。
data:
tables:
- tablename: measurements # 共享(默认)
columns: [ ... ]
- tablename: calibration_state # 内部使用——其他应用永远不可见
private: true
columns: [ ... ]访问权限是只读的,由用户按项目授予,并可随时撤销。完整模型以及读取提供方应用历史数据和实时数据流的 SDK 调用,请参见消费其他应用的数据。
特权访问
应用的容器与设备隔离运行,只拥有 Docker 的默认权限。有些应用需要更多:串口或 USB 适配器、GPIO、CAN 或蓝牙接口、主机网络。这就是特权访问。拥有特权访问的应用可以控制整台设备,包括其他应用及其数据,因此你的应用必须申请特权访问,由用户决定是否授予。
要申请特权访问,请在顶层添加带有 reason 的 privileged: 部分——它与 data: 平级,而不是嵌在其中:
privileged:
reason: "通过串口 /dev/ttyUSB0 读取 PLC"
data:
tables:
# ... 照常定义你自己应用的表reason 是必填项。它会在授权对话框中展示给用户,因此请为正在决定是否信任你的应用的人来写。
没有表的应用要在 privileged 旁边写上 data: {}:缺少 data: 键的 data-template.yml 无法发布。
用户授予的内容取决于应用的构建方式:
- 单镜像应用(只有
Dockerfile)在用户授权后以特权模式运行:拥有所有 Linux 能力(capabilities)、设备的/dev和主机的 D-Bus。如果没有声明,它运行时就没有主机的设备、额外的能力和主机的 D-Bus;版本仍会发布,构建日志中会给出警告。 - Docker Compose 应用只获得其
docker-compose.yml所申请的设置,授权对话框会列出这些设置。如果 compose 文件使用了下列任一设置,应用就必须声明privileged,否则发布版本会失败,错误信息会指出相应的服务和设置。compose 文件没有使用任何这些设置却声明了privileged,同样会失败。
以下 compose 设置被视为特权设置:
| 设置 | 何时视为特权 |
|---|---|
privileged | 除 false 以外的任何值 |
cap_add、devices、device_cgroup_rules | 有任何条目 |
security_opt | 有 no-new-privileges 以外的条目 |
network_mode、pid、ipc、uts、userns_mode、cgroup | 设为 host 或 container:… |
cgroup_parent | 设置了任何值 |
服务的 volumes | 挂载主机路径(/…、~/…、C:\…)、应用文件夹之外的路径(../…)或命名管道。只读的 /etc/localtime 和 /etc/timezone 不受影响。 |
volumes_from | 指定 container:… |
顶层 volumes | 某个卷带有 driver_opts、external 或固定的 name |
顶层 networks | 某个网络设置了 bridge 以外的 driver(如 macvlan、ipvlan 或 host)或 driver_opts,带有 external,或有固定的 name |
顶层 secrets、configs | 某个条目读取应用文件夹之外的 file |
命名卷、使用默认 bridge 驱动的网络、应用文件夹内的绑定挂载(./config:/config)、发布的端口以及 GPU 预留(gpus、deploy.resources.reservations.devices)都不属于特权设置。
在这些设置中使用 ${VAR} 占位符是允许的,但它同样被视为特权设置,因此也需要声明。借助这种方式,可以通过应用参数让用户选择串口:
services:
plc:
build: .
devices:
- "${SERIAL_PORT}:/dev/ttyS0"使用 include,或使用带 file 的 extends 的 compose 文件,无论是否声明都无法发布:一个版本只包含 docker-compose.yml。请把其他文件合并到其中。
只申请应用真正需要的权限。如果只需要一个串口,请编写只有一个服务并带有 devices: [/dev/ttyUSB0] 的 compose 文件,而不是使用单镜像或 privileged: true。用户能准确看到应用获得了什么,应用也无法做超出范围的事。
授权与撤销
- 安装时,用户会看到你的
reason,对于 compose 应用还会看到设置列表,并选择开启或关闭特权访问。拒绝绝不会阻止安装。 - 更新时,如果新版本申请特权访问而项目尚未授予,更新对话框会询问用户。即使拒绝,应用仍会更新;新版本随后在没有特权访问的情况下运行。
- 之后,特权访问是项目的应用设置中的一个开关,用户可以随时在那里撤销或授予。正在运行的设备会以新设置重启应用。
从云端 IDE 发起的开发运行遵循声明,没有开关:如果 .ironflock/data-template.yml 声明了 privileged,开发构建以特权模式运行,否则在没有特权访问的情况下运行。如果 compose 文件在没有声明的情况下使用了特权设置,开发构建会以与发布相同的错误失败。
未获授权时
应用照常启动。单镜像应用以 Docker 的默认权限运行:没有 /dev,没有额外的能力,也没有主机的 D-Bus。对于 compose 应用,设备代理会在启动应用之前从 compose 文件中删除特权设置,并在应用日志中写明从哪个服务删除了哪些设置。请确保你的代码在无法访问某些资源时(例如无法打开的串口)报告问题,而不是崩溃。
早期版本
在应用必须声明特权访问之前发布的版本,被视为申请了特权访问,现有的安装也会保留它,因此这些应用照常运行。用户可以像对待其他应用一样,在项目的应用设置中撤销它。从你的下一个版本起,如果应用需要特权访问,请声明 privileged。