uxiaohan/vh-kbstore repository overview

Turbo 的价格与免费上传政策可能变化。KBStore 将文件限制为 100 KB，但这不代表上传永远免费。公开部署前请核对 Turbo 最新政策。

⁠Github开源地址

KBStore - Github⁠

⁠⚙️ 环境配置

复制环境变量示例：

cp .env.example .env

PowerShell：

Copy-Item .env.example .env

编辑 .env：

SERVER_PORT=5888
DATABASE_PATH=./data/data.db
ARWEAVE_KEYFILE=./data/keyfile.json
SESSION_SECRET=replace-with-at-least-32-random-characters
SESSION_DAYS=7

开发环境未设置 SESSION_SECRET 时，KBStore 会为当前进程生成临时密钥，服务重启后已有会话失效。生产环境未显式配置时，服务会拒绝启动。

⁠🖥️ 运行 KBStore

使用一条命令构建前端并启动 Hono：

bun run serve

• Web 和 API：http://localhost:5888⁠

⁠📦 生产模式

bun run build
bun run start

Hono 会在 http://localhost:5888⁠ 同时提供 API 和 web/dist。通过 HTTPS 部署时应设置 NODE_ENV=production，以启用 Cookie 的 Secure 属性。

⁠🛡️ 权限模型

• 👑 首个账户 — 数据库中第一个注册账户自动成为管理员
• 👤 普通用户 — 只能查看自己的文件、Token 和个人统计
• 📊 管理区 — 所有登录用户都能进入管理区查看个人概览
• 🧰 管理员 — 可以查看全站统计、用户列表和所有账户的最新上传
• ❄️ 账户冻结 — 管理员可以冻结普通用户，其会话和 API Token 会立即失效
• 🔒 管理员保护 — 管理员不能冻结自己或其他管理员

⁠🔑 API Token

登录后打开 API Token 页面：

• 每个账户最多创建 6 个 Token
• 备注最多 8 个字符；留空时自动生成 6 位备注
• Token 默认隐藏，可以查看、复制或永久删除
• 通过 Authorization: Bearer 请求头使用 Token

上传文件：

curl -X POST http://localhost:5888/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@./example.txt"

响应示例：

{
  "file": {
    "id": 1,
    "txId": "...",
    "filename": "example.txt",
    "contentType": "text/plain",
    "size": 1234,
    "tokenNote": "CLI",
    "createdAt": 1785283200000,
    "url": "https://arweave.net/..."
  }
}

⁠🔎 文件查询

GET /api/files 只返回当前登录用户拥有的文件。

⁠📋 常用命令

⁠🔒 数据与安全

• Arweave 数据永久存在。删除 SQLite 只会删除本地索引，不会删除已经上传的数据。
• 当前项目没有数据库迁移系统。开发期间修改表结构后，需要删除 data/data.db、data/data.db-shm 和 data/data.db-wal。
• 为支持登录后再次查看完整 Token，API Token 以明文保存在 SQLite 中。数据库或备份泄露等同于全部 Token 泄露。
• .env、常见 Arweave keyfile 文件名、SQLite 文件、依赖和构建产物都已被 .gitignore 排除。
• 公网部署前应增加 HTTPS、反向代理、请求限流、注册风控、备份策略和日志审计。

⁠⚠️ 免责声明

• 用户应自行确保上传内容合法、合规，并拥有相应的存储和传播权利。
• Arweave 数据具有永久性。KBStore 无法撤回、修改或删除已成功写入网络的数据。
• 本项目不对第三方网关、ArDrive Turbo、Arweave 网络的可用性、价格、策略变化或数据传播延迟作出保证。
• 本项目按“原样”提供。使用者应自行评估部署安全、内容审核、隐私、费用及合规风险。
• Arweave、ArDrive、Turbo 及其他名称和商标归各自权利人所有，本项目与这些服务的运营方不存在官方隶属关系。