核心配置文件 — config.ini

config.ini 是核心元数据文件，定义应用的身份信息、展示信息、运行属性和依赖关系。是平台校验和应用中心展示的关键依据。

重要： 文件扩展名为 .ini，但内容必须为 严格 JSON 格式。禁止添加注释、使用单引号、多余逗号或任何语法错误。

格式说明： 文件扩展名 .ini 是公司历史使用习惯（与传统配置系统保持文件命名一致），但解析器按 JSON 格式处理。开发者务必使用 JSON 语法编写，否则将导致自动校验失败。

标准模板

以下为 config.ini 标准模板，按应用子类型分为三个独立示例。开发者根据自身应用类型，选择对应的模板。三选一，不可混用。

必读：字段互斥关系

应用类型	必设字段	禁止字段
WebUI 内部打开（iframe）	`type: "iframe"` + `path: "/<id>/"`	`open_path`
WebUI 外部打开（新标签页）	`open_path: true` + `path: "http://${ip}:<端口>"`	`type`
无 UI 服务	—	`type`、`open_path`、`path`

模板一：WebUI 内部打开（iframe 嵌入）

{
  "id": "dev-myapp",
  "icon": "/images/icons/dev-myapp.svg",
  "publisher": "开发者名称",
  "exec": true,
  "type": "iframe",
  "path": "/dev-myapp/",
  "resize": true,
  "maxmin": true,
  "width": 1180,
  "height": 680,
  "help": "https://example.com/docs",
  "version": "1.0.0",
  "recommend": false,
  "beta": false,
  "low_version": "TOS7.0",
  "category": ["Utilities"],
  "depend": [],
  "relation": [],
  "platform": "x86_64",
  "official": "https://example.com",
  "application_type": "deb",
  "system_id": "dev-myapp",
  "package": "dev-myapp",
  "user": "dev-myapp",
  "all_user_display": true,
  "allow_open_in_mobile": false
}

模板二：WebUI 外部打开（新标签页）

{
  "id": "dev-myapp",
  "icon": "/images/icons/dev-myapp.svg",
  "publisher": "开发者名称",
  "exec": true,
  "open_path": true,
  "path": "http://${ip}:8686",
  "help": "https://example.com/docs",
  "version": "1.0.0",
  "recommend": false,
  "beta": false,
  "low_version": "TOS7.0",
  "category": ["Utilities"],
  "depend": [],
  "relation": [],
  "platform": "x86_64",
  "official": "https://example.com",
  "application_type": "deb",
  "system_id": "dev-myapp",
  "package": "dev-myapp",
  "user": "dev-myapp",
  "all_user_display": true,
  "allow_open_in_mobile": false
}

模板三：无 UI 服务

{
  "id": "dev-myapp",
  "icon": "/images/icons/dev-myapp.svg",
  "publisher": "开发者名称",
  "exec": true,
  "help": "https://example.com/docs",
  "version": "1.0.0",
  "recommend": false,
  "beta": false,
  "low_version": "TOS7.0",
  "category": ["Utilities"],
  "depend": [],
  "relation": [],
  "platform": "x86_64",
  "official": "https://example.com",
  "application_type": "deb",
  "system_id": "dev-myapp",
  "package": "dev-myapp",
  "user": "dev-myapp",
  "all_user_display": true,
  "allow_open_in_mobile": false
}

字段参考

字段	类型	必填	说明	详细描述
`id`	string	✅ 是	应用唯一标识符	平台全局唯一，不可与已上架应用重复。字符集：小写字母（a-z）、数字（0-9）和连字符（-）。必须以字母开头。最大长度：50 字符。推荐格式：开发者账号标识-应用业务名称或域名倒装-业务应用名。示例：dev-admin-monitor、com-douyin-service。禁止纯通用系统关键词：docker、bin、var、api、usr、root、admin、system、service等。创建后不可修改。
`icon`	string	✅ 是	图标路径	仓库中的相对路径。必须遵循 `/images/icons/<id>.svg` 格式。图标文件必须存在于该路径。
`publisher`	string	✅ 是	发布者名称	在应用中心展示的开发者或组织名称。示例：`"Kevin"`、`"LinuxServer.io"`。
`path`	string	条件必填	应用访问地址	`path` 字段按场景互斥：iframe 用 `/<app_id>/`；外部打开用 `http://${ip}:<端口>`；无 UI 留空。必须使用 `${ip}` 占位符（如 `http://${ip}:8686`）。系统自动替换 `${ip}` 为 TNAS 局域网 IP。禁止写死固定 IP 或域名。非 80/443 端口：`http://${ip}:<端口>`。WebUI 内部打开（iframe）：`/<app_id>/`。无 UI 应用：设为 `""` 或省略该字段。`exec=true` 时必填。
`exec`	bool	✅ 是	是否有可执行服务	应用是否支持启停操作。`true`：应用中心显示启动/停止按钮；`false`：仅展示，无生命周期控制。
`open_path`	bool	条件必填	是否在新标签页打开	控制应用打开方式：`true` = 浏览器新标签页；`false` 或省略 = TOS 桌面内嵌 iframe。外部打开应用必须设为 `true`。与 `type` 互斥，不可同时设置。
`type`	string	条件必填	应用打开类型	WebUI 内部打开（iframe 嵌入）时设为 `"iframe"`。⚠️ 与 `open_path` 互斥，不可同时设置。外部打开或无 UI 应用不设置此字段。
`resize`	bool	否	窗口是否可拉伸	仅 `open_path=false` 时生效。控制应用弹窗是否可调整大小。默认 `false`。
`maxmin`	bool	否	窗口是否可最大化/最小化	仅 `open_path=false` 时生效。控制应用弹窗是否支持最大化/最小化。默认 `false`。
`width`	int	否	默认窗口宽度	仅 `open_path=false` 时生效。应用打开页面的宽度，默认值 1180。
`height`	int	否	默认窗口高度	仅 `open_path=false` 时生效。应用打开页面的高度，默认值 680。
`help`	string	否	帮助文档网址	指向帮助文档、Wiki 或社区教程的链接。无则留空。
`version`	string	✅ 是	应用版本号	遵循语义化版本号。每次提交必须唯一且递增。示例：`"1.0.0"`、`"2.3.1"`。
`recommend`	bool	✅ 是	是否推荐应用	`recommend` — 推荐标识，由平台运营人员在审核通过后根据应用质量统一设置。开发者提交时必须固定设置为 `false`，该字段由平台管理，开发者不得自行修改为 `true`。
`beta`	bool	✅ 是	是否测试版	`true` = 测试版，仅对测试用户展示；`false` = 正式版，全量用户展示。
`low_version`	string	✅ 是	支持的最低TOS版本	应用可正常运行的最低 TOS 版本。必须为 `TOS7.0` 及以上。格式：`"TOS7.0"`、`"TOS7.1"`。
`category`	[]string	✅ 是	应用分类	最多3个分类，从官方分类列表中选择（见附录A）。第一个分类为主要分类 — 决定应用的默认展示分区。按从最具体到最通用的顺序排列。超量分类将导致驳回。
`depend`	[]string	✅ 是	依赖应用列表	安装前必须先安装的应用 ID。必须为应用中心已有的应用 ID。依赖按列表顺序安装。示例：`["DockerEngine"]`。无依赖：`[]`。循环依赖将被驳回。
`relation`	[]string	否	关联应用列表	应用详情页"关联应用"模块展示的应用 ID。无强制依赖，仅展示关联。无关联：`[]`。
`platform`	string	✅ 是	目标架构	`"x86_64"` 或 `"aarch64"`。多架构需分别提交。
`official`	string	否	官方网站	应用官方网站链接。无则留空。
`application_type`	string	✅ 是	应用包类型	Deb 单包模式应用填 `"deb"`；双包模式/压缩包模式应用填 `"deb-TarGz"`；Docker 应用填 `"docker"`。
`system_id`	string	条件必填	Systemd 服务名	Deb 应用必填。必须与 systemd 服务文件名一致。Docker 应用留空。
`package`	string	条件必填	Deb 包名	Deb 应用必填。必须与 DEBIAN/control 中的 `Package` 字段一致。Docker 应用留空。
`compose_project`	string	条件必填	Docker Compose 项目名	Docker 应用必填。指定 docker-compose 项目创建时的名称，必须符合 Docker Compose 项目命名规范（仅小写字母、数字、连字符和下划线）。Deb 应用留空。示例：`"myapp-docker"`。 ⚠️ 注意：虽然 Docker Compose 允许下划线，但建议 `compose_project` 与 `id` 保持字符集一致以降低混淆。`id` 仅支持小写字母、数字和连字符（不含下划线），如果两者使用相同字符串，`compose_project` 中也请勿使用下划线。
`user`	string	✅ 是	运行用户	应用运行的系统用户。指定后自动创建专属用户（如 `"jellyfin"`）。Deb 应用需与 systemd 服务 `User` 字段匹配。严禁使用 root 用户。
`all_user_display`	bool	✅ 是	是否对所有用户展示	`true` = 所有 TNAS 用户可见；`false` = 仅管理员可见。当为 `false` 时，应用仅在管理员的应用程序中心视图中出现。非管理员用户无法看到或与该应用交互。应用仍在系统范围内安装并为所有用户运行；此设置仅控制可见性。
`allow_open_in_mobile`	bool	否	是否支持手机端打开	`true` = 该应用支持手机端打开；`false` = 该应用不支持手机端打开。默认 `false`。
`share_folders`	[]string	否	安装时创建共享文件夹	配置在安装时为应用创建共享文件夹，文件夹权限采用 ACL 管理。使用此字段必须保证 `user` 字段不为空。示例：`["data", "config"]`。

关键规则

JSON 格式校验：

提交前校验 config.ini：

# 使用 python3
python3 -c "import json; json.load(open('config.ini'))" && echo "JSON 格式有效"

# 使用 jq
jq empty config.ini

常见导致驳回的 JSON 错误：

{
  "id": "myapp",       // ❌ 对象最后一个字段末尾多余逗号
  "version": '1.0.0',  // ❌ 单引号（必须用双引号）
  // ❌ JSON 不允许注释
  "beta": false,
}

正确写法：

{
  "id": "myapp",
  "version": "1.0.0",
  "beta": false
}

❌ 全角引号："version"： "1.0.0" → ✅ 半角引号："version": "1.0.0"

IP 占位符：path 字段必须使用 ${ip}（如 http://${ip}:8686）。禁止写死固定 IP 或域名。
JSON 语法：必须是有效 JSON。禁止注释（// 或 /* */）、单引号或末尾多余逗号。
ID 唯一性：id 必须全局唯一。重复 ID 将被驳回。
版本递增：每次新提交的版本号必须大于前一版本。禁止重复或降级。
分类限制：每个应用最多3个分类。
TOS 版本：low_version 必须为 TOS 7.0 及以上。
字段一致性：version 在 config.ini、DEBIAN/control 和 app.lang 之间必须一致。system_id 必须与 systemd 服务文件名匹配。package 必须与 DEBIAN/control 的 Package 字段匹配。

path 字段取值速查表：

应用类型	打开方式	`path` 填写值	示例
Deb WebUI 内部打开	iframe 嵌入	`/<app_id>/`	`"/tmrtimer/"`
Deb WebUI 外部打开	新标签页	`/<app_id>/`	`"/weather/"`
Docker 应用	新标签页	`http://${ip}:<端口>`	`"http://${ip}:8080"`
无 UI 服务	无前端	省略或 `""`	—

注意

iframe 模式（内部打开）和外部打开的 path 格式相同（均为 /<app_id>/），区别在于 open_path 字段：内部打开 open_path=false（默认），外部打开 open_path=true。Docker 应用的 path 使用 http://${ip}:<端口> 格式。

保留字段： 以下字段名保留供未来平台使用。请勿在自定义 config.ini 中使用：host_network、container_runtime、sandbox、auto_update、upstream_url、license、min_memory、min_cpu、min_disk。使用保留字段可能导致未来兼容性问题和驳回。

标准模板​

字段参考​

关键规则​

标准模板

字段参考

关键规则