名称： static-files
描述： >
在子域名上托管静态文件，支持可选的身份验证。适用于需要在专用子域名上提供 HTML、图片、CSS、JS 或任何静态内容的场景。支持文件上传、基础认证、配额管理以及通过 Caddy 自动配置 SSL。命令包括 sf sites（创建/列出/删除）、sf upload（上传文件/目录）、sf files（列出/删除文件）。

静态文件托管

在 *.{domain} 子域名上托管静态内容，并自动配置 SSL。

快速参考

# 创建站点
sf sites create mysite
# → https://mysite.498as.com

# 上传文件
sf upload ./index.html mysite

# 上传目录
sf upload ./dist mysite

# 添加身份验证
sf sites auth mysite admin:secretpass123

# 列出文件
sf files mysite

# 删除文件
sf files mysite delete path/to/file.txt

# 删除站点
sf sites delete mysite

环境设置

export SF_API_URL=http://localhost:3000   # API 端点
export SF_API_KEY=sk_xxxxx                # 您的 API 密钥

工作流程

部署静态网站

# 1. 创建站点
sf sites create docs

# 2. 上传构建目录
sf upload ./build docs

# 3. 验证
curl -I https://docs.498as.com

受保护的文件共享

# 1. 创建带认证的站点
sf sites create private
sf sites auth private user:strongpassword

# 2. 上传敏感文件
sf upload ./reports private

# 3. 分享 URL 和凭据
# https://private.498as.com (用户 / 密码)

更新现有文件

# 覆盖现有文件
sf upload ./new-version.pdf mysite --overwrite

# 或先删除再重新上传
sf files mysite delete old-file.pdf
sf upload ./new-file.pdf mysite

CLI 命令

sites

upload

sf upload <path> <site> [subdir] [--overwrite] [--json]

• path: 要上传的文件或目录路径
• site: 目标站点名称
• subdir: 可选子目录
• --overwrite: 替换现有文件
• --json: 输出 JSON 格式

files

stats

sf stats              # 全局统计信息
sf stats <site>       # 站点特定统计信息

API 端点

基础 URL: $SF_API_URL，请求头需包含 Authorization: Bearer $SF_API_KEY

约束

• 站点名称: 仅限小写字母、数字、连字符（最多 63 个字符）
• 文件大小: 默认 50MB（可配置）
• 配额: 每个站点默认 100MB
• 速率限制: 每个 API 密钥每分钟 100 个请求

故障排除

"无法连接到 API"

# 检查服务状态
systemctl status kleo-static-files

# 检查端口是否在监听
curl http://localhost:3000/health

"无效的 API 密钥"

# 验证密钥是否已设置
echo $SF_API_KEY

# 如需创建新密钥
bun run /opt/kleo-static-files/scripts/create-key.ts "new-key"

"配额已满"

# 检查当前使用情况
sf stats mysite

# 删除未使用的文件
sf files mysite delete large-file.zip

站点无法通过 HTTPS 访问

# 验证 DNS 是否指向服务器
dig mysite.498as.com

# 检查 Caddy 配置
cat /etc/caddy/sites.d/static-files.caddy

# 重新同步 Caddy
bun run /opt/kleo-static-files/scripts/sync-caddy.ts --reload

安装

服务器安装（在主机上运行一次）

curl -fsSL https://raw.githubusercontent.com/498AS/kleo-static-files/main/install.sh | sudo bash

安装程序会输出 JSON 格式的连接信息，位于 KLEO_SF_CONFIG_BEGIN 和 KLEO_SF_CONFIG_END 标记之间。解析此 JSON 以获取 api_url 和 api_key。

安装后

export SF_API_URL=http://localhost:3000
export SF_API_KEY=sk_xxxxx  # 来自安装程序输出

检查状态

sudo /opt/kleo-static-files/install.sh --status

手动安装请参阅 references/install.md。