scriptforge/DESIGN.md

ScriptForge 设计文档

概述

脚本快速转运行链接服务。用户粘贴脚本内容，选择运行环境，生成一个短链。在终端执行 curl URL | <runtime> 即可运行脚本。

• 前端：Next.js (App Router + Tailwind CSS + TypeScript)
• 后端：Go (Gin + GORM + SQLite)
• 部署：Go embed 前端静态文件，单二进制部署
• CI/CD：Gitea Actions

核心流程

1. 用户打开首页 /
2. 粘贴脚本内容（上限 16KB）
3. 选择运行环境（bash / zsh / sh / fish / python3 / node / ruby / php）
4. 选择过期时间（1小时 / 24小时 / 7天 / 30天）
5. 提交 → 后端存入 SQLite → 返回短链 ID
6. 页面展示生成的命令：curl https://example.com/raw/xK8mPq | bash
7. 用户可以复制命令到终端执行

API 设计

POST /api/scripts — 创建脚本

请求体：

{
  "content": "#!/bin/bash\necho hello",
  "runtime": "bash",
  "expires_in": "24h"
}

响应：

{
  "id": "xK8mPq",
  "admin_token": "dGhpcyBpcyBhIHRva2Vu",
  "url": "https://example.com/raw/xK8mPq",
  "command": "curl https://example.com/raw/xK8mPq | bash",
  "runtime": "bash",
  "expires_at": "2026-05-29T16:27:00Z"
}

GET /api/scripts/:id — 获取脚本元数据

响应：

{
  "id": "xK8mPq",
  "runtime": "bash",
  "content_length": 25,
  "created_at": "2026-05-28T16:27:00Z",
  "expires_at": "2026-05-29T16:27:00Z",
  "expired": false
}

注意：此接口不返回脚本原始内容（内容通过 /raw/:id 获取），避免前端二次暴露。

GET /raw/:id — 获取脚本纯文本内容

• 响应头 Content-Type: 根据 runtime 设置对应 MIME（见运行时配置表）
• 响应头 Content-Disposition: attachment; filename="script.<ext>"（根据 runtime 设置扩展名）
• 响应体：脚本纯文本内容
• 如脚本已过期，返回 404

DELETE /api/scripts/:id?token=xxx — 删除脚本

• 需要 admin_token 参数
• 成功返回 204

数据模型

type Script struct {
    ID          string    `gorm:"primaryKey;size:8"`
    Content     string    `gorm:"type:text;not null"`
    Runtime     string    `gorm:"size:16;not null;index"`
    AdminToken  string    `gorm:"size:64;not null"`
    ExpiresAt   time.Time `gorm:"not null;index"`
    CreatedAt   time.Time `gorm:"not null"`
}

运行时配置

Runtime	扩展名	MIME 类型	命令模板
bash	.sh	text/x-shellscript	curl {url} | bash
zsh	.zsh	text/x-shellscript	curl {url} | zsh
sh	.sh	text/x-shellscript	curl {url} | sh
fish	.fish	text/x-shellscript	curl {url} | fish
python3	.py	text/x-python	curl {url} | python3
node	.js	text/javascript	curl {url} | node
ruby	.rb	text/x-ruby	curl {url} | ruby
php	.php	text/x-php	curl {url} | php

运行环境列表在 Go 后端定义为常量数组，用于校验请求中的 runtime 字段。

过期策略

• 用户保存时选择：1小时 / 24小时 / 7天 / 30天
• 后端定时任务（每分钟扫描一次），删除过期记录
• 过期后 /raw/:id 返回 404，详情页标记为已过期

限流策略

• 创建接口：10 次/分钟/IP
• 其他接口：60 次/分钟/IP
• 请求体上限：17KB

安全设计

• 完全公开，无需注册/登录
• 创建时返回 admin_token（随机 64 位字符串），持有者可删除脚本
• 无内容过滤，靠过期机制和限流控制风险
• 编辑功能：无（admin_token 仅用于删除，不能改内容。设计上 script 是一次性的，编辑会带来版本管理等复杂问题）

前端路由

路由	页面	说明
/	首页	粘贴脚本 + 选择运行环境/过期时间 + 提交 + 结果展示
/s/[id]	脚本详情页	展示脚本内容（语法高亮）、元数据、curl 命令卡片
/s/[id]/delete	删除确认页	输入 admin_token 确认删除

项目目录结构

scriptforge/
├── frontend/                  # Next.js 项目
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx           # 首页
│   │   │   ├── layout.tsx         # 根布局
│   │   │   └── s/[id]/
│   │   │       ├── page.tsx       # 脚本详情页
│   │   │       └── delete/
│   │   │           └── page.tsx   # 删除确认页
│   │   ├── components/
│   │   │   ├── ScriptForm.tsx     # 脚本提交表单
│   │   │   ├── ResultCard.tsx     # 结果展示卡（含复制按钮）
│   │   │   ├── ScriptViewer.tsx   # 脚本内容展示（语法高亮）
│   │   │   └── CommandCard.tsx    # curl 命令展示卡
│   │   └── lib/
│   │       └── api.ts            # API 调用封装
│   ├── package.json
│   └── next.config.js
├── backend/                   # Go 项目
│   ├── cmd/
│   │   └── server/
│   │       └── main.go            # 入口
│   ├── internal/
│   │   ├── handler/
│   │   │   ├── script.go          # 脚本 CRUD handlers
│   │   │   └── raw.go             # 原始内容 handler
│   │   ├── model/
│   │   │   └── script.go          # GORM model
│   │   ├── service/
│   │   │   └── script.go          # 业务逻辑
│   │   ├── middleware/
│   │   │   └── ratelimit.go       # 限流中间件
│   │   └── config/
│   │       └── runtime.go         # 运行时配置列表
│   ├── go.mod
│   └── go.sum
├── .gitea/
│   └── workflows/
│       └── deploy.yml             # Gitea Actions 部署流程
├── Makefile                    # 统一构建命令
├── DESIGN.md                   # 本设计文档
└── README.md

CI/CD 部署流程（Gitea Actions）

1. 触发条件：push 到 main 分支
2. 构建步骤：
   • cd frontend && npm ci && npm run build → 输出 out/
   • cd backend && cp -r ../frontend/out ./internal/embed && go build -o server ./cmd/server
3. 部署步骤：
   • scp 二进制到服务器
   • ssh 执行 systemctl restart scriptforge

后续可扩展方向

• 大模型集成：根据脚本内容自动推荐运行环境
• 更多运行时：dockerfile、powershell、deno、bun 等
• 脚本版本管理（不基于 admin_token，需要真正的用户系统）
• 统计数据：脚本执行次数、来源 IP 等（需要跟踪 curl 请求）
• WebSocket 实时执行输出流