Getting Started
快速启动
5 分钟内让 RaisFast 运行起来 — 安装、启动、开始构建。
本指南将以最快的方式带你从零开始运行 RaisFast 服务。
第 1 步 — 启动服务
确保已安装 RaisFast（参见安装），然后直接运行：
raisfast完成。服务默认监听 http://0.0.0.0:9898，所有配置均有合理默认值。
首次运行会发生什么？
- 数据库 — SQLite 文件自动创建于
./storage/db/raisfast.db - Schema — 所有表通过
IF NOT EXISTS自动创建 - APP_KEY — 32 字节加密密钥自动生成并持久化到
.env
验证运行状态
curl http://localhost:9898/health在浏览器中打开：
| URL | 描述 |
|---|---|
http://localhost:9898/admin | 管理后台 SPA |
http://localhost:9898/api/docs | Swagger UI (OpenAPI) |
http://localhost:9898/api/v1/routes | 列出所有已注册路由 |
http://localhost:9898/api/v1/info | 服务名称、版本、API 风格 |
初始化管理员
创建初始管理员账号：
# 使用默认值：admin@raisfast.dev / admin / admin123
raisfast db seed
# 或指定凭据
raisfast db seed --email admin@example.com --username superadmin --password MyStr0ngP@ss种子命令是幂等的 — 如果用户名已存在则跳过。
测试 API
# 管理员登录
curl -X POST http://localhost:9898/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"admin@raisfast.dev","password":"admin123"}'
# 创建文章（将 TOKEN 替换为登录返回的 access_token）
curl -X POST http://localhost:9898/api/v1/admin/posts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"title":"Hello World","content":"My first post!"}'第 2 步 — 创建项目（可选）
如需使用内容类型和插件的结构化项目，使用脚手架命令：
# 创建空白项目
raisfast app new my-site
# 使用模板创建
raisfast app new my-blog -t blog
raisfast app new my-shop -t ecommerce生成的目录结构：
my-site/
├── config.toml
├── .env.example
├── .gitignore
├── extensions/
│ ├── content_types/ — 内容类型 TOML 定义
│ └── plugins/ — 插件 JS/Lua/WASM 文件
├── migrations/
├── data/
├── logs/
└── public/uploads/然后配置并运行：
cd my-site
cp .env.example .env
raisfast db migrate # 仅用于后续的 Schema 更新
raisfast db seed
raisfast常用配置
最简 .env 配置：
APP_ENV=development
DATABASE_URL=sqlite:./storage/db/raisfast.db?mode=rwc其余设置都有合理的默认值。以下是最重要的环境变量：
# ── 核心 ──
APP_HOST=0.0.0.0
APP_PORT=9898
APP_ENV=development # development | production
# ── 安全（生产环境必须修改） ──
JWT_SECRET=change-me-in-production-at-least-32-chars
JWT_ACCESS_EXPIRES=900 # 15 分钟
JWT_REFRESH_EXPIRES=604800 # 7 天
# ── 存储 ──
STORAGE_DRIVER=local # local | s3
UPLOAD_DIR=./storage/uploads
MAX_UPLOAD_SIZE=104857600 # 100 MB
# ── 插件 ──
PLUGIN_DIR=./extensions/plugins
PLUGIN_HOT_RELOAD=false
# ── 搜索 ──
SEARCH_ENGINE=none # none | tantivy
# ── 后台任务 ──
WORKER_ENABLED=false
WORKER_CONCURRENCY=2生产环境检查清单
部署到生产环境前，请确保：
- 修改
JWT_SECRET— 生产模式下服务会拒绝使用默认值启动 - 设置
CORS_ORIGINS— 生产模式下服务会拒绝未设置此项的启动 - 设置
APP_ENV=production— 启用生产安全检查 - 启用 TLS — 通过
TLS_CERT_PATH/TLS_KEY_PATH或反向代理 - 设置
BASE_URL— 正确的媒体 URL、RSS 订阅等所必需 - 备份策略 — 使用
raisfast db backup或配置外部备份
APP_ENV=production
JWT_SECRET=<your-strong-secret-at-least-32-chars>
CORS_ORIGINS=https://yourdomain.com
BASE_URL=https://api.yourdomain.comCLI 参考
RaisFast 提供了功能完整的命令行工具：
raisfast <command> [options]服务管理
| 命令 | 描述 |
|---|---|
raisfast server start | 启动 HTTP 服务 |
raisfast server stop | 停止运行中的服务 |
raisfast server restart | 重启服务 |
raisfast server status | 查看运行状态 |
数据库
| 命令 | 描述 |
|---|---|
raisfast db migrate | 执行待处理的迁移 |
raisfast db rollback | 回滚上一批迁移 |
raisfast db backup | 备份数据库到带时间戳的文件 |
raisfast db seed | 创建初始管理员 |
脚手架
| 命令 | 描述 |
|---|---|
raisfast app new <name> | 创建新项目 |
raisfast ct new <name> | 创建内容类型 TOML 文件 |
raisfast plugin new <id> | 创建插件脚手架 |
诊断
| 命令 | 描述 |
|---|---|
raisfast doctor | 系统诊断 |
raisfast route list | 列出所有已注册路由 |
raisfast route stats | 路由统计 |