Skip to content

About

轻量级 OpenAI 兼容 API 服务器;曾在单核 ARM Cortex-A7、32MB 内存测试环境中承受 10 个并发请求。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

TinyStation

一个面向 ARMv7 与小内存设备 的轻量级 API 服务器,兼容 OpenAI API。单个 Go 二进制、无数据库、无前端构建步骤、无第三方运行时依赖。内置管理后台,提供统一 API Key、上游节点池、调度与故障转移、用户 bugs 额度、限流、熔断、用量与成本统计、运行指标,以及可选的精确响应缓存。

已有硬件测试记录

项目 测试情况
处理器 单核 ARM Cortex-A7
内存 32MB
并发 当时测试可承受 10 个并发请求

以上为项目已有的硬件测试记录。

本机快速体验

安装 Go(版本要求见 go.mod),在项目目录运行:

go run -ldflags="-X main.version=1.4.67" . -addr 127.0.0.1:8080 -data ./data

打开 http://127.0.0.1:8080,用户名为 admin,初始密码见首次启动日志或 data/initial-password.txt。首次启动后,在管理后台配置上游 API;邮箱注册需要配置 SMTP。完整构建与部署步骤见下文。


1. 架构

客户端 / SDK
  Authorization: Bearer sk-ts-...
        │
        ▼
接入层 /v1/*
  HMAC Key 校验 → 用户状态 → bugs 额度 → 每用户并发准入
        │
        ▼
调度层
  优先级分组 + failover
  adaptive / weighted_rr / round_robin / least_conn / consistent_hash
  健康、延迟、余量、权重、成本
        │
        ├──────────────┬──────────────┐
        ▼              ▼              ▼
   Upstream A      Upstream B      Upstream C
   主供应商         备用供应商       本地模型

控制面:/  统一登录 → 用户/密钥/上游/策略/缓存
持久化:config.json + stats.json + master.key(均 0600)

一次请求:

  1. 解析 Bearer Key,做 HMAC 哈希查找,检查 Key / 用户状态与过期时间。
  2. 检查用户 bugs 额度;1 bug = 1 次请求。管理员账号不消耗额度。
  3. 获取该用户的并发槽位(固定 10;登录、注册、邮箱和状态接口不经过此闸门)。
  4. 读取 JSON 请求体(默认上限 1MB),提取 model 与 stream。
  5. 校验 Key 与账户的模型白名单。
  6. 调度器过滤启用、模型匹配、未熔断、未超上游日配额、未超节点并发的节点。
  7. 按优先级分组;组内按策略排序;按 max_retries 有限故障转移。
    • 优先级会按最近延迟自动微调:≤800ms 提升 2 级、≤2s 提升 1 级、>8s 降低 1 级;显式 priority 仍是基线。
  8. 转发请求;流式响应逐行转发并解析 usage。
  9. 记录 Key / 用户 / 上游 / 全局日统计,并更新全站 RPM、CPU、内存指标。

普通用户登录后只能看到自己的密钥、bugs 余额、用量和请求记录;管理员登录后在同一界面额外看到用户、上游和全局设置。


2. 能力

层 已实现
用户与登录 统一登录页;用户名或邮箱 + 密码;独立注册页需要邮箱验证码;会话 Cookie + CSRF
角色 admin 可管理用户、额度、上游、全局设置;user 只能管理自己的密钥和查看自己的用量/记录
注册 注册页先验证 163 / QQ / Outlook 邮箱,验证通过后才创建用户;默认 0 bugs
配额 每个用户一个 bugs 额度;1 bug = 1 次请求;只有管理员可以分配;默认 0;管理员账号不消耗额度
接入层 统一 sk-ts-... API Key;HMAC-SHA256 哈希存储;只显示一次明文;支持 Authorization: Bearer 与 X-Api-Key
调度层 优先级分组、故障转移;自适应、平滑加权轮询、轮询、最少连接、加权一致性哈希
健康与熔断 主动 HTTP 健康检查;被动失败计数;连续失败熔断;冷却后半开探测;失败退避
上游池 动态增删、启停、自动拉取模型、模型白名单、权重、优先级、成本系数、每日请求余量、节点最大并发、多 Key 轮询
治理层 每用户并发(固定 10)、用户 bugs 额度、模型白名单、超时、有限重试、精确缓存
多租户 每个用户一个隐藏的额度边界;用户只接触自己的 Key,不再暴露“项目”概念
计费/用量 请求数、输入/输出/总 Token、相对成本、缓存命中、按日统计、最近请求日志
运行指标 管理员面板底部显示系统 CPU、内存、进程 RSS、全站 RPM;普通用户不暴露系统指标
安全 PBKDF2 账号密码、邮箱验证码、会话 Cookie、CSRF、同源检查、登录/发信限速、API Key 失败限速、上游 Key AES-GCM、请求大小/并发/超时限制、CSP、CDN no-store 头

不包含

  • 分布式多实例共享配额/会话/熔断状态(需要 Redis/Postgres)。
  • 语义缓存、向量缓存、真实支付账单。cost_per_1k 只是相对成本系数。
  • 自动申请 TLS 证书、WAF、DDoS 清洗、2FA、细粒度 RBAC 权限组。
  • WebSocket;multipart 上传返回 415(只支持 JSON 的 OpenAI 兼容端点)。
  • 跨实例共享 API Key 哈希(HMAC 使用本机 master key)。

3. 调度与治理

3.1 优先级与故障转移

  • priority 数字越小越先尝试;节点先按 priority 分组。
  • 只在同一 priority 组内执行策略排序;组内失败后再进入下一组。
  • max_retries(0–3)决定最多尝试几个候选。默认 2,最多尝试 3 个候选。
  • 重试条件:连接/传输错误、401/403(换密钥/渠道)、408/425、429、502/503/504。
  • 流式请求在收到第一个有效 SSE 数据前不会向客户端提交响应头;空流、SSE error 事件、模型不可用会继续切换渠道。一旦首个有效数据写出,不再重试,避免重复半截 SSE。
  • 上游错误正文不会转发给客户端;重试耗尽后统一返回 503 upstream_unavailable,避免客户端看到供应商的余额/模型/HTML 报错。
  • 上游响应头超时 12 秒;流式首个有效数据超时 20 秒,超时会自动换渠道。
  • Cherry Studio 的模型探测请求(system=test, hi)使用 3 秒/渠道、最多 4 个候选的快速探测预算,可在其 15 秒超时内完成切换。
  • 重试使用已缓存的请求体(默认 ≤1MB),不会重放无限流。

3.2 策略

策略 行为
adaptive 默认。综合权重、延迟 EWMA、在途连接、上游日配额余量、成本系数打分
weighted_rr 平滑加权轮询
round_robin 组内轮询
least_conn 优先在途请求最少,其次延迟更低
consistent_hash 以 tenant_id + model 做加权 rendezvous 哈希,尽量固定到同一节点

自适应评分近似:

weight × quota_remaining_ratio
────────────────────────────────────────────
(1 + latency_ms / 500) × (1 + inflight × 0.7) × (1 + cost_per_1k)

3.3 健康检查与熔断

  • 定时 HEAD/GET 健康路径(默认 30 秒);成功恢复 healthy。
  • 上游连续失败达到阈值后进入 down,冷却期内不参与调度;冷却后半开探测。
  • 429:该 上游 + Key + 模型 熔断 1 分钟;同渠道其他密钥/模型仍可继续服务。
  • 上游 401/403:该密钥熔断 5 分钟,自动换同渠道其他密钥。
  • 模型返回 model not found / not exist / unsupported 等:该 上游 + Key + 模型 熔断 5 分钟;后续请求直接跳过这个组合,换其他渠道。
  • 余额/额度不足(如 You exceeded your current quota、insufficient_quota、billing、payment required):该 Key 熔断 1 小时。
  • Key 无效/认证失败:该 Key 熔断 1 小时;账号被停用/封禁:该 Key 熔断 24 小时。
  • 所有错误响应都会先做语义分类再决定是否重试,避免对余额耗尽、Key 失效的渠道持续打请求。
  • 一个上游可以配置多个 API Key(换行/逗号分隔),按轮询使用;每个 Key 独立熔断。
  • 冷却结束后只允许一个半开探测;探测成功才恢复,失败会再次延长熔断,不会被用户并发请求反复拉起。
  • 如果所有渠道的 Key/模型组合都在熔断中,直接返回 503,不会继续打上游。
  • 面板显示 healthy / degraded / down / disabled,以及熔断剩余时间。

3.4 并发与超时

  • 每个用户固定 10 个并发槽位;超出返回 503 server_busy。
  • 没有全局并发闸门;多用户并发总量由 WAF/反向代理和机器内存共同约束。
  • 登录、注册、邮箱验证码、/api/state 等控制面请求不消耗并发槽位。
  • 普通请求默认 120 秒;流式请求默认 300 秒;上游响应头等待 90 秒。
  • 请求体默认 1MB;非流式响应硬上限 2MB;SSE 单行解析上限 256KB。

3.5 Bugs 额度

  • 单位是 bugs,1 bug = 1 次请求。
  • 每个用户默认 0 bugs,只能由管理员在「用户」页分配。
  • 每次通过认证并进入转发流程的请求消耗 1 bug;失败请求同样消耗。
  • 管理员账号不消耗 bugs。
  • 用户不能修改自己的额度,也不能给其他用户分配额度。
  • 用户只能看到自己的已用/剩余 bugs。

3.6 缓存

  • 默认关闭;开启后只缓存成功的非流式、JSON、无敏感头请求。
  • Key 为 tenant_id + model + 请求体哈希,按账户隔离。
  • 内存 LRU;默认 TTL 60 秒、128 条、2MB。
  • 缓存命中在日志标记 CACHE,仍计入用量和 bugs。
  • CDN 侧必须对 /v1/* bypass,不能依赖 CDN 缓存。

4. 快速开始

# Windows:交叉编译 ARMv7 + 本地 Windows 二进制
.\build.ps1

# 本地运行
go run . -addr 127.0.0.1:8080 -data .\data

或:

make test
make arm          # dist/tinystation-linux-armv7

首次启动会打印:

  TinyStation 1.4.67
  console  : http://127.0.0.1:8080/
  username : admin
  password : XXXXXXXXXXXXXXXXX
  saved to : ./data/initial-password.txt

打开 /,使用用户名或邮箱 + 密码登录。管理员账号 admin 的初始密码在首次启动日志和 data/initial-password.txt 中。

新用户访问 /register:先输入 163 / QQ / Outlook 邮箱并完成验证码验证,再设置用户名和密码。验证通过前不会创建用户;创建后默认 0 bugs,只能看到自己的密钥、额度和请求记录。管理员分配 bugs 后才能调用 API。

首启环境变量(可选)

TINYSTATION_ADMIN_PASSWORD='change-me-please' \
UPSTREAM_BASE_URL='https://api.deepseek.com/v1' \
UPSTREAM_API_KEY='sk-...' \
UPSTREAM_NAME='主供应商' \
UPSTREAM_MODELS='deepseek-chat,deepseek-reasoner' \
./tinystation -addr :8080 -data /opt/tinystation/data

只在首次创建配置时生效;已有 config.json 后不会覆盖。忘记密码使用 -reset-password,会重置管理员用户 admin 的密码并生成新的 initial-password.txt。

命令行

参数 环境变量 默认 说明
-addr TINYSTATION_ADDR :8080 监听地址
-data TINYSTATION_DATA ./data 数据目录
-tls-cert TINYSTATION_TLS_CERT 空 内置 TLS 证书
-tls-key TINYSTATION_TLS_KEY 空 内置 TLS 私钥
-reset-password — — 生成新的管理员登录密码并退出;需先停服务
-version — — 打印版本

其他环境变量:

变量 默认 说明
TZ 系统 统计日切与显示时区;建议 Asia/Shanghai
GOMEMLIMIT 20MiB Go 软内存上限;程序仅在未设置时写入
GOGC 50 GC 百分比
TINYSTATION_MAX_CONCURRENCY 10 兼容保留;实际并发限制按用户固定 10
TINYSTATION_TRUST_PROXY 0 为 1 时信任 X-Forwarded-For / X-Forwarded-Proto / X-Real-IP
TINYSTATION_CLIENT_IP_HEADER 空 可信代理/CDN 的专用客户端 IP 头,如 CF-Connecting-IP;仅 TRUST_PROXY=1 时生效
TINYSTATION_MASTER_KEY 自动生成 32 字节 base64;加密上游 Key、HMAC API Key
TINYSTATION_SITE_NAME TinyStation 首启站点名
TINYSTATION_SMTP_HOST smtp.qiye.aliyun.com SMTP 服务器
TINYSTATION_SMTP_PORT 465 SMTP 端口
TINYSTATION_SMTP_USERNAME 空 SMTP 登录账号(通常是发件邮箱)
TINYSTATION_SMTP_PASSWORD 空 SMTP 密码/授权码;为空则关闭邮箱登录
TINYSTATION_SMTP_FROM 空 发件人地址
TINYSTATION_SMTP_TLS 端口为 465 时 1 1 使用隐式 TLS,0 使用 STARTTLS
TINYSTATION_ADMIN_EMAIL 空 绑定管理员账号的邮箱;例如 info@example.com

5. 用户、登录与后台

登录页只有一个入口:

  • 登录:一个输入框接受 用户名或邮箱,配合密码登录。
  • 注册:独立页面 /register;先验证 163 / QQ / Outlook 邮箱,再设置用户名和密码。
  • 邮箱验证码验证通过前不会创建用户;注册成功后自动登录。
  • 管理员用户名为 admin,也可以用绑定的管理员邮箱登录;初始密码在首次启动日志和 data/initial-password.txt 中。
  • 管理员和普通用户共用同一个登录页,没有单独的“管理员登录页”。

普通用户登录后看到:

  • 概览:自己的今日请求、Token、成功率、密钥数、14 天趋势、最近请求。
  • 我的密钥:新建/编辑/停用/删除自己的 Key,查看每个 Key 的今日/累计用量。
  • 账户:修改自己的登录密码、查看 API Base URL。
  • 看不到用户管理、额度管理、上游节点、系统 CPU/内存、全站 RPM。

管理员登录后额外看到:

  • 用户:查看邮箱验证创建的账号、编辑角色/状态、分配 bugs 额度、重置密码、删除用户。不能绕过邮箱验证新建用户。
  • 模型:显示每个渠道已同步的模型列表和来源;只有至少一个 Key 未熔断的模型才会出现在 /v1/models,冷却后会自动重新出现。支持 并发检测全部,后台根据 /proc/stat 动态调整并发(初始 4 路,目标 CPU 约 50%,最高 12 路)。检测进度写入 model_check_state.json,重启后从断点继续;完整检测 6 小时内不重复全量。空模型列表渠道接受任意模型,但不会出现在该页面。
  • 上游:Base URL、上游 Key、自动请求 /v1/models 拉取模型列表(新增/保存后自动排队同步)、启用、优先级、权重、成本系数、日请求上限、节点并发、熔断阈值、冷却、健康检查路径、测活、手动同步模型。
  • 设置:调度策略、重试、普通/流式超时、健康检查间隔、最大请求体、CORS、缓存、开放注册、客户端接入。
  • 运行指标(管理员概览底部):系统 CPU、内存、进程 RSS、全站 RPM。

全站 RPM 统计的是通过认证的 /v1/* 请求,包括 /v1/models、缓存命中和上游错误;不包含无效 Key 和管理后台请求。普通用户只能看自己的请求记录。

新用户默认额度

  • Bugs:0
  • 1 bug = 1 次请求
  • 管理员账号不消耗 bugs
  • 管理员可在「用户」页分配;用户不能自行修改

用户停用后其 Key 立即失效;删除用户会同时删除该用户的 Key 和额度。


6. API 使用

Base URL:http://<host>:8080/v1

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-ts-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hello"}]}'

流式:

curl -N http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-ts-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","stream":true,"messages":[{"role":"user","content":"hello"}]}'

支持:

  • POST /v1/chat/completions
  • POST /v1/completions
  • POST /v1/embeddings
  • GET /v1/models
  • 其他 OpenAI 兼容的 JSON POST 路径按透明代理处理;multipart/form-data 返回 415。

错误示例:

{"error":{"message":"quota exceeded","type":"invalid_request_error","code":"insufficient_quota"}}

常见状态:401 invalid_api_key、403 model_not_allowed、429 insufficient_quota / rate_limit_exceeded、503 server_busy / no_healthy_upstream、502 upstream_error。


7. RV1103 部署

7.1 拷贝与启动

mkdir -p /opt/tinystation/data
scp dist/tinystation-linux-armv7 root@device:/opt/tinystation/tinystation
ssh root@device 'chmod +x /opt/tinystation/tinystation'

scp deploy/S99tinystation root@device:/etc/init.d/S99tinystation
ssh root@device 'chmod +x /etc/init.d/S99tinystation && /etc/init.d/S99tinystation start'
ssh root@device 'cat /opt/tinystation/data/initial-password.txt'

/etc/tinystation.env 示例:

TZ=Asia/Shanghai
GOMEMLIMIT=14MiB
GOGC=40
TINYSTATION_MAX_CONCURRENCY=10
TINYSTATION_DATA=/opt/tinystation/data
TINYSTATION_LOG=/opt/tinystation/tinystation.log

修改登录密码后 initial-password.txt 会删除。管理员用户名为 admin,也可用绑定邮箱登录;普通用户使用用户名或邮箱 + 密码登录。

邮箱登录需要设置 TINYSTATION_SMTP_* 与 TINYSTATION_ADMIN_EMAIL。SMTP 密码只放在服务端环境变量中,不写入 config.json,也不会返回给前端。

7.2 内存预算

  • 最大请求体 1MB;非流式响应硬上限 2MB;每用户并发 10。
  • 流式响应不整体缓冲,SSE 行缓冲上限 256KB;流式总时长默认 300 秒。
  • 缓存默认关闭,开启后上限 2MB。
  • 二进制约 7.8MB;运行时堆通常几 MB。
  • 用户历史按 30 天保存,面板展示 14 天趋势。

7.3 服务管理

/etc/init.d/S99tinystation start
/etc/init.d/S99tinystation stop
/etc/init.d/S99tinystation restart
tail -f /userdata/tinystation/tinystation.log

服务脚本支持 TINYSTATION_BASE、TINYSTATION_DATA、TINYSTATION_LOG、TINYSTATION_PID、TINYSTATION_MAX_CONCURRENCY 等环境变量。

7.4 网络与时钟

  • 设备无 RTC 时,启动后需通过宿主机同步时间;否则 TLS 证书校验会失败。
  • USB 网络可配合 deploy/S98tinystation-net 设置默认路由/DNS。
  • 宿主机可用 adb forward tcp:8080 tcp:8080 暴露到本机。
  • 公网部署建议 Nginx/CDN 终止 TLS,并设置 TINYSTATION_TRUST_PROXY=1。

8. CDN / 反向代理

必须遵守:

  • /v1/*、/api/*、/admin/*(旧地址重定向)、/healthz、/readyz 全部 bypass,不要缓存。
  • /、/register、/app.css?v=...、/app.js?v=... 可以缓存:登录外壳对所有访客相同,不含会话数据。
  • POST、SSE、带 Authorization / X-Api-Key 的请求禁止缓存。
  • 静态外壳响应带:
Cache-Control: public, max-age=60, stale-while-revalidate=120
CDN-Cache-Control: public, max-age=60, stale-while-revalidate=120
  • 静态资源带版本号,响应带:
Cache-Control: public, max-age=86400, stale-while-revalidate=604800, immutable
  • /v1/* 和 /api/* 继续发送:
Cache-Control: no-store, no-cache, must-revalidate, private, max-age=0, no-transform
CDN-Cache-Control: no-store
Surrogate-Control: no-store
Vary: Authorization, X-Api-Key
  • SSE 响应带 X-Accel-Buffering: no,Nginx 关闭 proxy_buffering。
  • Nginx 超时 ≥ 600 秒;不要改写 Authorization。
  • 只信任 CDN 回源网段;用 CDN 专用客户端 IP 头并设置 TINYSTATION_CLIENT_IP_HEADER。
  • CDN 日志脱敏 Authorization、X-Api-Key、请求体。

Nginx 片段:

location /v1/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

9. 安全模型

9.1 资产

  1. 上游供应商 API Key(直接造成费用)。
  2. 管理员/用户登录密码与会话。
  3. 用户 API Key。
  4. 请求/响应内容。
  5. 配额、统计与成本数据。

9.2 已实现的控制

攻击面 控制
API Key 猜测 256-bit 随机 Key;HMAC-SHA256 存储;按 IP 失败限速;无明文落盘
登录密码爆破 PBKDF2-SHA256 120k;8 次/10 分钟封 5 分钟;PBKDF2 单飞
邮箱验证码滥用 仅允许 163 / QQ / Outlook;60 秒重发冷却;每 IP 发信限速;验证码 10 分钟过期、5 次尝试;验证码只存 HMAC
会话劫持 32 字节随机会话;HttpOnly;SameSite=Lax;TLS 下 Secure;30 天过期;改密/停用后失效
越权 每次请求重新读取用户状态;admin/user 角色在服务端强制校验;普通用户只能访问自己的 Key/记录
CSRF 所有登录态写请求要求 X-CSRF-Token;Origin/Host 同源;Sec-Fetch-Site: cross-site 拒绝
XSS 无第三方脚本;CSP;所有动态文本 HTML 转义
点击劫持 X-Frame-Options: DENY + CSP frame-ancestors 'none'
请求体 DoS 默认 1MB;管理端 128KB;登录/邮箱接口 8KB;MaxBytesReader
响应体 DoS 非流式响应 2MB 上限;SSE 单行 256KB 解析上限;流式总时长限制
并发 DoS 每用户 10 并发;节点并发;登录/注册不经过并发闸门,由 WAF/反向代理保护
慢请求 10 秒读头、60 秒读请求、120 秒普通请求、300 秒流式、上游响应头 90 秒
配额绕过 用户 bugs 额度按已认证请求计数;管理员账号例外;用户停用后其 Key 立即失效
上游 Key 泄露 AES-256-GCM 加密;master.key 或环境变量;管理页只显示后四位
日志泄露 不记录请求头/Key/提示词
SSRF 仅管理员可配上游;拒绝非 http/https、URL 用户信息、链路本地/未指定 IP、云元数据主机名;禁止自动跟随重定向
开放重定向 上游不跟随重定向;只转发白名单请求头
敏感缓存 API/管理响应源站 no-store;登录外壳与带版本静态资源公共缓存
跨域 CORS 默认关闭;开启也只允许 * 且不携带 Cookie
CDN 缓存泄露 API/管理响应 no-store + bypass;登录外壳不含会话数据,公共缓存;Vary: Authorization, X-Api-Key
信息泄露 错误响应不返回堆栈;panic 只写服务端日志;状态接口不返回密码/完整 Key/上游 Key;普通用户看不到系统指标和其他用户

9.3 残余风险

  1. 单机应用层隔离:隔离依赖程序逻辑,不是内核/容器隔离。
  2. 管理员拥有 SSRF 能力:可配置内网 http/https 上游;必须保护管理员账号和 /admin 来源。
  3. master.key 与 config.json 同目录:整个数据目录被拖走则可解密上游 Key;应限制权限并分离备份。
  4. TINYSTATION_TRUST_PROXY=1:没有可信代理时可伪造 IP,绕过 IP 限速。
  5. API Key 是 Bearer Token:泄露即可用;没有签名、mTLS、IP 绑定。请用 TLS 和配额。
  6. 缓存复用敏感响应:同一账户下不同 Key 会共享源站缓存;敏感业务关闭缓存或分账户。
  7. Token 统计依赖上游:上游不返回 usage 时计为 0,不能作为严格财务账单。
  8. 注册依赖 SMTP 可达性:SMTP 故障时无法注册新用户;已有用户仍可用用户名/邮箱 + 密码登录。
  9. 会话持久化到 data/sessions.json:重启后仍有效;限速/熔断/RPM 仍在内存。
  10. 单核 CPU:PBKDF2 和大规模请求会占 CPU;公网请前置代理/WAF。
  11. 主机 root:能读 master.key 的攻击者可解密上游 Key、修改二进制。
  12. 每用户并发 10:没有全局并发闸门;多个用户同时发大请求仍可能 OOM,需要 WAF/接入层限制。
  13. 角色只有 admin/user:没有细粒度权限组;管理员可以管理所有用户和额度。

9.4 上线检查

  • /admin 仅管理网段可达;API 与后台上不同域名/策略。
  • 全链路 HTTPS;HTTP 仅绑定 127.0.0.1。
  • 修改默认 admin 密码;确认 initial-password.txt 已删除。
  • 设置 TZ、TINYSTATION_TRUST_PROXY(仅可信代理时)。
  • 配置 TINYSTATION_SMTP_* 和 TINYSTATION_ADMIN_EMAIL;SMTP 密码只放环境变量,文件权限 0600。
  • 根据业务决定是否开放注册;关闭后 /register 不可创建新账号。
  • 为普通用户分配合理的 bugs 额度;默认 0,未分配无法调用 API。
  • 每个用户独立 Key;额度只由管理员调整。
  • 备份 config.json、master.key,备份介质加密。
  • 保持源站缓存关闭,除非确认同账户 Key 互信。
  • CDN 对 /v1/*、/api/*、/admin/*(旧地址)、/healthz、/readyz 全部 bypass;/、/register、/app.css?v=*、/app.js?v=* 可缓存。
  • CDN/Nginx 不缓冲 SSE,超时 ≥ 600s。
  • CDN/Nginx 覆盖 X-Forwarded-For,只信任 CDN 回源网段。
  • CDN 日志脱敏 Authorization。
  • 监控 CPU、内存、/healthz、/readyz、全站 RPM。
  • 定期轮换上游 Key。

10. 数据与备份

data/
├── config.json          # 用户、Key 哈希、上游、设置、密码哈希(0600)
├── config.json.bak      # 上一次配置(0600)
├── stats.json           # 累计/按日统计、按账户日统计(0600)
├── stats.json.bak
├── master.key           # 32 字节随机密钥(0600)
└── initial-password.txt # 首次启动生成;改密后删除
  • config.json 写入采用临时文件 + rename,保留 .bak。
  • config.json 损坏时自动尝试 .bak;两者都坏则拒绝启动,不会静默重置。
  • stats.json 丢失只会丢统计,不影响 Key/上游。
  • config.json 丢失但 master.key 在:上游 Key 无法恢复,需重新配置。
  • 迁移设备:同时复制 config.json 与 master.key,或设置同一个 TINYSTATION_MASTER_KEY。
  • 备份命令示例:
cd /opt/tinystation/data
tar -czf /secure-backup/tinystation-$(date +%F).tgz \
  config.json config.json.bak master.key stats.json

11. 测试

go test ./...
go vet ./...
node --check web/app.js

覆盖(节选):

  • 登录、CSRF、会话、密码修改、初始密码文件删除;
  • 邮箱注册验证、用户名/邮箱双入口登录、角色隔离、普通用户只能访问自己的 Key;
  • 管理端空数组初始化、配置损坏不重置;
  • 上游调度、重试、熔断、SSE、usage 统计;
  • bugs 额度、缓存、CDN no-store 头;
  • 全站 RPM 窗口、客户端 IP 专用头;CPU/内存在 Linux 板端手工验证。

12. 目录

main.go                 # 启动、参数、初始化
app.go                  # 路由、中间件、HTTP server
model.go                # 结构体、默认值、归一化
storage.go              # 配置/统计持久化、用户与 API Key 认证
security.go             # AES-GCM、HMAC、PBKDF2、原子文件
auth.go                 # 会话、登录限速、Cookie、IP
users.go                # 邮箱注册、用户/角色/额度管理、用户 Key
email_login.go          # 邮箱验证码发送、注册校验
mail.go                 # SMTP 客户端、验证码存储
admin.go                # 管理 API 与状态视图
runtime.go              # 调度、健康、并发、限流
metrics.go              # /proc 指标、RPM 窗口
cache.go                # 响应缓存
proxy.go                # /v1 反向代理、SSE、配额
logs.go                 # 请求日志环
web.go                  # 嵌入静态资源
web/                    # 登录页 + 管理/用户 SPA
deploy/                 # RV1103 init、USB 网络、NAT 示例

13. 限制

  • 单实例、内存态限速/会话/熔断;重启清空。
  • 无自动 TLS、WAF、2FA、细粒度 RBAC。
  • 成本是相对系数,不是真实账单。
  • 每用户并发固定 10、没有全局闸门;64MB 设备处理大请求仍需压测和 WAF。
  • 普通用户的“用量”以账户为边界;同一账户下的多个 Key 共享统计。
  • 新用户默认 0 bugs,必须由管理员分配后才可以调用 API。
  • 邮箱验证码依赖 SMTP;SMTP 故障时新用户无法注册,已有用户仍可登录。

About

轻量级 OpenAI 兼容 API 服务器;曾在单核 ARM Cortex-A7、32MB 内存测试环境中承受 10 个并发请求。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages