Static Files Hosting
Host static content on *.{domain} subdomains with automatic SSL.
Quick Reference
CODEBLOCK0
Environment Setup
CODEBLOCK1
Workflows
Deploy a Static Website
CODEBLOCK2
Protected File Sharing
CODEBLOCK3
Update Existing Files
CODEBLOCK4
CLI Commands
sites
| Command | Description |
|---|
| INLINECODE1 | List all sites |
| INLINECODE2 |
Create new site |
|
sf sites delete <name> | Delete site and all files |
|
sf sites auth <name> <user:pass> | Set basic auth |
|
sf sites auth <name> --remove | Remove auth |
upload
CODEBLOCK5
- -
path: File or directory to upload - INLINECODE7 : Target site name
- INLINECODE8 : Optional subdirectory
- INLINECODE9 : Replace existing files
- INLINECODE10 : Output JSON
files
| Command | Description |
|---|
| INLINECODE11 | List all files |
| INLINECODE12 |
Delete specific file |
stats
CODEBLOCK6
API Endpoints
Base: $SF_API_URL with Authorization: Bearer $SF_API_KEY
| Method | Path | Description |
|---|
| GET | INLINECODE15 | List sites |
| POST |
/sites | Create site |
| DELETE |
/sites/{name} | Delete site |
| PATCH |
/sites/{name} | Update auth |
| GET |
/sites/{name}/files | List files |
| POST |
/sites/{name}/files | Upload file |
| DELETE |
/sites/{name}/files/{path} | Delete file |
| GET |
/stats | Global stats |
| GET |
/stats/{name} | Site stats |
| GET |
/health | Health check |
Constraints
- - Site names: lowercase, alphanumeric, hyphens only (max 63 chars)
- File size: 50MB default (configurable)
- Quota: 100MB per site default
- Rate limit: 100 requests/minute per API key
Troubleshooting
"Cannot connect to API"
CODEBLOCK7
"Invalid API key"
CODEBLOCK8
"Quota exceeded"
CODEBLOCK9
Site not accessible via HTTPS
CODEBLOCK10
Installation
Server Installation (run once on host)
CODEBLOCK11
The installer outputs JSON with connection details between KLEO_SF_CONFIG_BEGIN and KLEO_SF_CONFIG_END markers. Parse this to get api_url and api_key.
After Installation
CODEBLOCK12
Check Status
CODEBLOCK13
See references/install.md for manual installation.
静态文件托管
在 *.{domain} 子域名上托管静态内容，并自动配置 SSL。
快速参考
bash
创建站点
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
环境配置
bash
export SFAPIURL=http://localhost:3000 # API 端点
export SFAPIKEY=sk_xxxxx # 您的 API 密钥
工作流程
部署静态网站
bash
1. 创建站点
sf sites create docs
2. 上传构建目录
sf upload ./build docs
3. 验证
curl -I https://docs.498as.com
受保护的文件共享
bash
1. 创建带身份验证的站点
sf sites create private
sf sites auth private user:strongpassword
2. 上传敏感文件
sf upload ./reports private
3. 分享 URL 和凭据
https://private.498as.com (user / strongpassword)
更新现有文件
bash
覆盖现有文件
sf upload ./new-version.pdf mysite --overwrite
或删除后重新上传
sf files mysite delete old-file.pdf
sf upload ./new-file.pdf mysite
CLI 命令
sites
| 命令 | 描述 |
|---|
| sf sites list | 列出所有站点 |
| sf sites create <name> |
创建新站点 |
| sf sites delete
| 删除站点及所有文件 |
| sf sites auth | 设置基本身份验证 |
| sf sites auth --remove | 移除身份验证 |
upload
bash
sf upload [subdir] [--overwrite] [--json]
- - path：要上传的文件或目录
- site：目标站点名称
- subdir：可选子目录
- --overwrite：替换现有文件
- --json：输出 JSON 格式
files
| 命令 | 描述 |
|---|
| sf files <site> | 列出所有文件 |
| sf files <site> delete <path> |
删除指定文件 |
stats
bash
sf stats # 全局统计
sf stats # 站点特定统计
API 端点
基础地址：$SFAPIURL，使用 Authorization: Bearer $SFAPIKEY
/sites | 创建站点 |
| DELETE | /sites/{name} | 删除站点 |
| PATCH | /sites/{name} | 更新身份验证 |
| GET | /sites/{name}/files | 列出文件 |
| POST | /sites/{name}/files | 上传文件 |
| DELETE | /sites/{name}/files/{path} | 删除文件 |
| GET | /stats | 全局统计 |
| GET | /stats/{name} | 站点统计 |
| GET | /health | 健康检查 |
限制
- - 站点名称：小写字母、数字、仅限连字符（最多 63 个字符）
- 文件大小：默认 50MB（可配置）
- 配额：每个站点默认 100MB
- 速率限制：每个 API 密钥每分钟 100 个请求
故障排除
无法连接到 API
bash
检查服务状态
systemctl status kleo-static-files
检查端口是否在监听
curl http://localhost:3000/health
无效的 API 密钥
bash
验证密钥是否已设置
echo $SFAPIKEY
如有需要，创建新密钥
bun run /opt/kleo-static-files/scripts/create-key.ts new-key
超出配额
bash
检查当前使用情况
sf stats mysite
删除未使用的文件
sf files mysite delete large-file.zip
站点无法通过 HTTPS 访问
bash
验证 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
安装
服务器安装（在主机上运行一次）
bash
curl -fsSL https://raw.githubusercontent.com/498AS/kleo-static-files/main/install.sh | sudo bash
安装程序会在 KLEOSFCONFIGBEGIN 和 KLEOSFCONFIGEND 标记之间输出包含连接详细信息的 JSON。解析此内容以获取 apiurl 和 apikey。
安装后
bash
export SFAPIURL=http://localhost:3000
export SFAPIKEY=sk_xxxxx # 来自安装程序输出
检查状态
bash
sudo /opt/kleo-static-files/install.sh --status
手动安装请参阅 references/install.md。
