快速开始

HackerStart 是一个面向中国客户的 TanStack Start SaaS 全栈应用模板，内置多租户、组织管理、AI 能力、支付与管理后台，帮助你更快把想法上线。

前提条件

1. Node.js

Node.js v22+，用来在本地执行 JavaScript 代码。

macOS 用户可以使用 brew 安装：

brew install node

或前往 Node.js 官方网站下载 LTS 版本。

node --version

2. Git

Git 是版本控制工具，用来跟踪代码历史、协作开发。

macOS 用户安装 Xcode 后自动包含 Git，或前往 Git 官方网站下载。

git --version

3. pnpm

包管理器，用来安装依赖。我们推荐使用 pnpm。

# 使用 npm 安装 pnpm
npm install -g pnpm
# 其他安装方式：https://pnpm.io/installation
# 查看版本号
pnpm -v

4. GitHub CLI

GitHub CLI（gh）用来将密钥同步到 GitHub，以便通过 GitHub Actions 实现自动化部署。安装并登录：

# macOS 安装
brew install gh

# 其他平台安装方式：https://github.com/cli/cli#installation

# 登录 GitHub
gh auth login

# 确认账号状态
gh auth status

5. Docker（可选）

HackerStart 使用 InsForge 作为数据库和认证服务。本地开发时，InsForge 通过 Docker 运行。

如果你还没有安装 Docker，推荐以下两种方式：

OrbStack — 轻量快速，macOS 推荐
Docker Desktop — 官方方案

docker --version

如果你使用 InsForge Cloud（云端托管），则不需要本地 Docker。

小贴士：推荐使用 Warp 终端，支持多标签页、主题切换和命令补全。

开始动手（4 步）

1. 克隆项目

将仓库代码下载到本地。你可以把 your-project-name 换成自己的项目名。

git clone https://github.com/HackerStart/hackerstart-saas-suite.git your-project-name
cd your-project-name

克隆后移除原始远程仓库，创建你自己的私有仓库：

# 移除原始远程仓库
git remote remove origin

# 创建你自己的私有仓库（需要 GitHub CLI）
# 如果没有 gh 命令，可以在 GitHub 网页上手动创建
gh repo create your-project-name --private --source=. --remote=origin
git push -u origin main

2. 安装依赖

pnpm install

3. 设置环境变量

复制示例文件，然后按注释填写。

cp .env.example .env

核心变量说明：

变量	必需	说明
`INSFORGE_URL`	✅	InsForge 服务地址
`INSFORGE_ANON_KEY`	✅	InsForge 匿名密钥
`INSFORGE_API_KEY`	✅	InsForge API 密钥（仅服务端）
`VITE_INSFORGE_URL`	✅	浏览器端 InsForge 地址
`VITE_INSFORGE_ANON_KEY`	✅	浏览器端 InsForge 密钥
`SESSION_SECRET`	✅	Session 加密密钥（`openssl rand -base64 32`）

详细的环境变量说明见《环境变量配置》。

4. 启动开发服务器

pnpm dev

打开 http://localhost:3000，你应该能看到 HackerStart 首页。

下一步

《配置系统设置》— 初始化数据库和管理面板
《环境变量配置》— 完整的环境变量参考
《部署到 EdgeOne Pages》— 部署上线

本页内容