StartOS TypeScript SDK使用指南：快速开发服务包

StartOS TypeScript SDK（@start9labs/start-sdk）是一个专为StartOS自托管平台设计的TypeScript框架，提供强类型API和构建器模式，帮助开发者轻松定义服务包的清单、守护进程、健康检查、网络接口、操作、备份、依赖项和配置等核心组件。通过本指南，你将快速掌握如何利用SDK构建和部署自己的服务包。

📋 准备工作：环境搭建与依赖安装

系统要求

• Node.js 14+ 环境
• npm 或 yarn 包管理器
• Git 版本控制工具

安装步骤

1. 克隆项目仓库

   git clone https://gitcode.com/GitHub_Trending/st/start-os cd start-os/sdk

2. 安装依赖
   SDK已固定zod版本为4.3.6以确保兼容性，执行以下命令安装依赖：

   npm install

图1：StartOS服务包开发环境示意图（背景图展示StartOS的星空主题UI风格）

🔨 核心功能与快速上手

1. 定义服务清单（Manifest）

清单是服务包的核心配置，包含名称、描述、版本等元数据。使用setupManifest函数创建类型安全的清单：

import { setupManifest } from '@start9labs/start-sdk' const manifest = setupManifest({ id: 'my-service', name: 'My Service', version: '1.0.0', description: 'A sample service built with StartOS SDK', // 更多配置项... })

2. 配置服务生命周期

通过setupInit和setupUninit函数定义服务在安装、更新、卸载等阶段的行为：

// 安装时初始化逻辑 export const init = sdk.setupInit(async ({ effects }) => { await effects.runCommand('echo "Service initialized"') }) // 卸载时清理逻辑 export const uninit = sdk.setupUninit(async ({ effects }) => { await effects.runCommand('rm -rf /data/my-service') })

3. 网络接口与依赖管理

使用setupInterfaces配置端口绑定，通过setupDependencies声明服务依赖：

// 配置HTTP接口 export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => { effects.createInterface({ name: 'http', protocol: 'tcp', port: 8080, host: '0.0.0.0', }) }) // 声明依赖项 export const dependencies = sdk.setupDependencies({ 'postgres': { version: '^13.0.0' }, })

图2：StartOS服务市场界面（展示已部署的服务包列表）

📚 项目结构与最佳实践

推荐目录结构

sdk/ ├── src/ │ ├── setupManifest.ts // 服务清单配置 │ ├── setupMain.ts // 主服务逻辑 │ ├── setupInterfaces.ts // 网络接口配置 │ ├── setupBackups.ts // 备份策略 │ └── setupDependencies.ts // 依赖管理 ├── package.json └── tsconfig.json

关键API参考

🚀 构建与部署

打包服务包

执行以下命令生成.s9pk格式的服务包：

npm run build

部署到StartOS

1. 通过StartOS web界面上传生成的.s9pk文件
2. 按照提示完成安装与配置

📖 更多资源

• 官方文档：sdk/README.md
• 架构设计：sdk/ARCHITECTURE.md
• 贡献指南：sdk/CONTRIBUTING.md

通过StartOS TypeScript SDK，开发者可以快速构建符合自托管生态的服务包，充分利用TypeScript的类型安全特性和StartOS的强大功能。立即开始探索，将你的服务带入自托管的未来！