快速开始

本章节帮助开发者在 5 分钟内完成第一个 TOS 7 应用的开发与上架。

前置准备

一台运行 TOS 7.0（当前稳定版/测试版）的 TNAS 设备 — 推荐但非必需

没有 TNAS 硬件？

没问题。即使没有实体 TNAS 设备，也可以开发 TOS 应用。只要开发环境满足推荐的配置（参见第 6 章 · 开发环境），即可使用 Ubuntu 22.04 虚拟机或远程测试设备等替代方案进行构建和测试。

基础的 Linux 命令行操作能力
GitHub 或 Gitee 账号（用于代码托管与开发者平台关联）

五步上架流程

第 1 步：注册开发者账号

访问 TOS 开发者平台，注册并完成开发者认证。

第 2 步：选择应用类型

你的应用特征	推荐类型
原生二进制、Python 脚本（利用系统预装 Python 3.10）、轻量级系统服务	Deb 应用
需要独立运行环境、复杂依赖、多容器架构	Docker 应用

注意

Node.js、Java、Go 等语言运行时非 TOS 系统预装，Deb 应用不可直接依赖。详见第 2 章 · 应用架构策略。

第 3 步：选择项目模板

根据你的应用类型，使用对应的 GitHub 模板仓库：

模板仓库	打包方式	适用场景
Deb 应用模板（单包）	单包模式	从零开发的新应用，所有文件统一打包
Deb 应用模板（双包）	双包模式	已有通用标准 deb 包的应用
Docker 应用模板	Docker	Docker 容器化部署

注意

子类型（WebUI 内部/外部/无 UI）与打包方式（单包/双包）是两个独立维度，可交叉组合。单包和双包均支持三种子类型。

每个模板仓库均包含：完整目录结构、config.ini、多语言文件、systemd 服务、前后端示例代码、生命周期脚本、构建脚本（build.sh）、GitHub Actions CI/CD 配置。点击仓库页面的 "Use this template" 按钮即可创建你的项目。

第 4 步：本地开发与测试

# Deb 应用：构建并测试安装
dpkg-deb --build ./<应用根目录> ./<appid>_<version>_<arch>.deb
sudo dpkg -i <appid>_<version>_<arch>.deb
sudo systemctl status <system_id>

# Docker 应用：启动测试
docker-compose up -d
curl http://localhost:<端口>/health

第 5 步：提交审核

将代码推送至 GitHub 或 Gitee 公开仓库
在仓库中创建 Release 并将包文件上传为 Release 资源（详细命名和格式要求见第 15 章 · 第 3 步）
在开发者平台创建应用，关联 GitHub/Gitee 仓库
提交审核；平台将自动从你的 Release 中拉取包并执行自动校验，随后进入人工审核
审核通过后，应用将发布至 TOS 应用中心

说明： 开发者平台会自动从你的 GitHub/Gitee Release 中拉取应用包，无需手动上传。详细的包格式、命名和 Release 要求见第 15 章 · 上架流程。

关键检查清单

提交审核平台前，请确认以下事项：

config.ini 是合法 JSON 格式（无注释、无尾随逗号、仅双引号）
app.lang 包含全部 14 种语言（未翻译语种用英语填充）
图标为 SVG 格式，存放于 /images/icons/<appid>.svg
systemd 服务文件 User 非 root
版本号严格递增，config.ini、DEBIAN/control、app.lang 中一致
在真实 TNAS 设备或替代测试环境上完成安装/启动/停止/卸载全流程测试（参见第 6 章 · 开发环境）

没有 TNAS 硬件？

没问题。即使没有实体 TNAS 设备，也可以开发和测试 TOS 应用。只要开发环境满足推荐的配置（参见第 6 章 · 开发环境），Ubuntu 22.04 虚拟机或远程测试设备等替代方案同样适用。

常见踩坑避坑清单

在正式开发前，请特别注意以下两个最常见的跨平台问题，避免提交后被驳回：

Top 1：换行符问题（CRLF to LF）

现象： 在 Windows 上编辑的脚本部署到 TOS 后，报 bad interpreter: No such file or directory
根因： Windows 默认使用 CRLF 换行，Linux 只认 LF
解决： 提交前确保所有脚本和配置文件使用 LF 换行

# 快速检查项目中的 CRLF 文件
grep -rl $'\r' *.sh *.py *.ini *.lang *.service *.conf 2>/dev/null

# 一键转换（Linux/macOS）
sed -i 's/\r$//' *.sh *.py *.ini *.lang *.service *.conf

详细规范见第 7 章 · 包规范 — 跨平台换行符。

Top 2：Node.js 依赖缺失

现象： 应用启动时报 node: command not found
根因： TOS 系统不预装 Node.js，Deb 应用不能直接依赖 node 环境
解决： 改用 Go 编译静态二进制，或使用 Python 3.10（系统已预装）

更多策略见第 2 章 · 应用架构策略 — 非预装依赖处理规范。

前置准备​

五步上架流程​

关键检查清单​

常见踩坑避坑清单​

Top 1：换行符问题（CRLF to LF）​

Top 2：Node.js 依赖缺失​