routeros-app-yaml

RouterOS /app YAML 格式（7.21+）

RouterOS 7.21 引入了 /app 路径（内置应用列表和管理功能）。完整的 YAML 应用创建功能（/app/add）在 7.22 中推出（首次出现在 7.22beta5 中）。可以把它看作 MikroTik 提供的一种固执己见的 docker-compose 替代方案——但它不是 docker-compose，且两者存在显著差异。

/app 是什么

/app 子系统允许用户在 YAML 中将一个或多个容器定义为一个“应用”。RouterOS 会解析 YAML，创建容器、卷、网络和配置文件，然后管理其生命周期。

关键概念：

• 每个 /app 都通过包含服务、配置、卷和网络的 YAML 文档定义
• YAML 通过 CLI（/app/add yaml-url=...）或 REST API 加载到 RouterOS 中
• 内置应用随 RouterOS 一起提供（可通过 GET /rest/app 查看）
• 可通过 URL 或内联 YAML 添加自定义应用
• 应用商店（app-store-urls=）提供精选合集

与 docker-compose 的关键差异

功能	docker-compose	RouterOS /app
端口格式	host:container[/protocol]	两种格式（见下文）
环境变量	KEY=value 或列表	相同，但支持占位符展开
卷	命名卷或绑定挂载	子集——不支持绑定挂载选项
网络	完整的 Docker 网络模型	简化版——名称 + 外部网络
构建	完整的 Dockerfile 支持	基础支持（context + dockerfile）
配置	Docker 配置 API	仅支持内联 content
部署/资源	支持	不支持
顶层 version:	已弃用（曾为必填项）	不使用
文件扩展名	.yml / .yaml	.tikapp.yaml（约定）

顶层属性

属性	类型	必填	说明
name	string	否	/app 的唯一标识符
descr	string	否	在应用 UI 中显示的可读描述
page	string (URI)	否	项目主页 URL
category	string (enum)	否	应用商店分类
icon	string (URI)	否	图标 URL（当 show-in-webfig=yes 时在 WebFig 中显示）
default-credentials	string 或 null	否	在 UI 中显示的 username:password
url-path	string	否	用于浏览器访问的 URL 路径后缀（例如 /admin）
credentials	string	否	凭据提示（可替代 default-credentials）
option	boolean	否	应用是否为可选项
auto-update	boolean	否	每次启动时拉取并重启容器
services	object	是	容器服务定义（至少需要 1 个）
volumes	object	否	命名卷声明
networks	object	否	网络声明
configs	object	否	带内联内容的配置文件声明

类别值（完整列表）

productivity, storage, networking, development, communication,
file-management, search, video, media, media-management,
home-automation, monitoring, database, automation, ai,
messaging, radio, security, business

MikroTik 添加内置应用时会出现新的类别。CI 架构验证会检测这些类别。

服务属性

services: 下的每个键都定义一个容器。必需属性：image。

属性	类型	说明
image	字符串	容器镜像（省略注册表即可使用 /container/config 的 registry-url）
container_name	字符串	显式名称；用作 /container 下文件路径的基础名称
hostname	字符串	容器主机名
entrypoint	字符串或字符串[]	覆盖默认入口点
command	字符串或字符串[]	覆盖默认命令
ports	数组	端口映射（参见格式一节）
environment	对象或数组或 null	环境变量（KEY=value 列表或 {KEY: value} 映射）
volumes	字符串数组	卷挂载（例如 my-vol:/data）
configs	对象数组	配置文件放置位置（{source, target, mode}）
restart	枚举	no、always、on-failure、unless-stopped
depends_on	数组或对象	服务依赖顺序
devices	字符串数组	传递给容器的设备映射
user	字符串	运行容器所用的用户
security_opt	字符串数组	安全选项
shm_size	字符串	共享内存大小
stop_grace_period	字符串或整数	SIGKILL 前的等待时间
ulimits	对象	资源限制（例如 nofile: {soft: 65536, hard: 65536}）
build	对象或字符串	构建配置（context、dockerfile、args）
healthcheck	对象	健康检查（test、interval、timeout、retries、start_period）
stdin_open	布尔值	保持 stdin 打开
expose	数组	内部端口（不发布到主机）
secrets	字符串数组	要公开的密钥
attach	布尔值	附加到标准输入输出

端口格式 — 两种写法

RouterOS 支持两种端口映射字符串格式，两种都有效；7.23beta2 及更高版本中的新应用优先使用冒号格式。

旧版 OCI 风格（7.23 之前）

[ip:]host_port:container_port[/tcp|/udp][:label]

示例：

ports:
  - "8080:80/tcp"
  - "8443:443/tcp:https"
  - "192.168.1.1:53:53/udp:dns"

新版 RouterOS 风格（7.23+）

[ip:]host_port:container_port[:label][:tcp|:udp]

协议使用冒号而非斜杠追加：

ports:
  - "8080:80:web:tcp"
  - "8443:443:https:tcp"
  - "53:53:dns:udp"

长格式（对象）语法

ports:
  - target: 80
    published: 8080
    protocol: tcp
    name: web
    app_protocol: http

端口中的 IP 地址和占位符

端口字符串可以包含字面 IP 地址或占位符表达式：

ports:
  - "[accessIP]:[accessPort]:80/tcp:web"      # Old style with placeholders
  - "[accessIP]:[accessPort]:80:web:tcp"       # New style with placeholders

占位符

RouterOS 会在部署时展开以下占位符：

占位符	展开为
[accessIP]	从外部访问应用时使用的 IP 地址
[accessPort]	外部访问的主机主端口
[accessPort2]	次要主机端口
[containerIP]	分配给容器的 IP 地址
[routerIP]	路由器自身的 IP 地址

占位符可出现在端口映射、环境变量值和配置内容中。

配置（内联文件）

顶层的 configs: 用于声明配置内容；服务会引用这些配置：

configs:
  my-config:
    content: |
      server {
        listen 80;
        server_name [accessIP];
      }

services:
  web:
    image: nginx:alpine
    configs:
      - source: my-config
        target: /etc/nginx/conf.d/default.conf
        mode: 0644

卷和网络

volumes:
  app-data: {}      # Named volume (null or empty object)

networks:
  app-net:
    name: my-network
    external: true   # Use existing RouterOS network

存储库架构（app-store-urls）

RouterOS 可以从通过 app-store-urls= 配置的 URL 加载应用集合。存储库格式就是一个 YAML 数组，其中包含 /app 定义：

- name: app-one
  services:
    web:
      image: nginx:alpine
- name: app-two
  services:
    db:
      image: postgres:16

按照惯例，存储库文件使用 .tikappstore.yaml 扩展名。

/app 的 REST API

// List all /app entries (built-in + custom)
const apps = await fetch(`${base}/app`, auth).then(r => r.json());

// Each entry has: .id, name, yaml (raw YAML string), and metadata
// The 'yaml' field is a RouterOS string containing the full YAML document

// Add a custom /app from URL
await fetch(`${base}/app`, {
  method: "PUT",
  ...auth,
  body: JSON.stringify({ "yaml-url": "https://example.com/my-app.tikapp.yaml" }),
});

注意：/app 端点要求安装 container 额外软件包。

用于验证的 JSON Schema

每个 /app 文档都有两种 Schema 变体：

Schema	用途	端口验证	环境变量名称
*.latest.json	CI/严格验证	强制执行正则表达式模式	仅限 ^[A-Z_][A-Z0-9_]*$
*.editor.json	编辑器/SchemaStore 用户体验	无正则表达式（允许自动补全）	不区分大小写

严格 Schema 在端口字符串上使用正则 pattern，这会 阻止 VSCode 自动补全——YAML 扩展不会为带有模式的字段提供建议。编辑器变体移除了这些模式。

VSCode 集成

将以下内容添加到 VSCode 设置中，以启用 YAML 自动补全：

{
  "yaml.schemas": {
    "https://tikoci.github.io/restraml/routeros-app-yaml-schema.latest.json": "*.tikapp.yaml",
    "https://tikoci.github.io/restraml/routeros-app-yaml-store-schema.latest.json": "*.tikappstore.yaml"
  }
}

使用 .editor.json URL 可获得更好的自动补全，但验证严格性会降低。

版本历史

• 7.22：初始支持 /app，提供基本服务属性
• 7.23beta2：新增冒号样式的端口格式（:tcp/:udp 后缀）
• 7.23+：新增服务属性（devices、expose、secrets、attach）

常见错误

• 误以为兼容 docker-compose——并非支持所有属性，部分属性的行为也有所不同
• 使用 version: 键——RouterOS 会忽略它；无需使用
• 在同一条目中混用端口格式——每个端口字符串必须且只能使用一种格式
• 严格验证要求环境变量名称使用大写——混合大小写时请使用 *.editor.json
• 忘记容器软件包——未安装额外的 container 软件包时，/app 会返回 404
• 使用 deploy: 或 resources:——RouterOS 不支持

其他资源

• RouterOS 基础知识、CLI 语法和 REST API：请参阅 routeros-fundamentals 技能
• 在 QEMU 中运行 CHR（测试 /app 所需）：请参阅 routeros-qemu-chr 技能
• MikroTik 论坛参考资料：https://forum.mikrotik.com/t/amm0s-manual-for-custom-app-containers-7-22beta/268036/22