self-host.md
May 29, 2025 · View on GitHub
QBin 自托管部署教程
本文将帮助您快速部署 QBin 服务，分别提供三种灵活的部署方式，适合不同的使用场景和技术偏好。
⚡ 部署方式选择
| 部署方式 | 适用场景 | 难度 | 稳定性 |
|---|---|---|---|
| Docker Compose | 本地或服务器部署，适合生产环境 | 很简单 | 高 |
| Docker | 快速测试或简单部署 | 很简单 | 高 |
| Deno Deploy | 无需服务器，快速云端部署 | 很简单 | 高 |
| Deno CIL | 本地开发环境和调试测试 | 简单 | 中 |
🐳 Docker Compose 一键部署（推荐）
最简单的部署方式，一键完成环境配置和应用启动：
# 克隆项目仓库
git clone https://github.com/Quick-Bin/qbin.git
# 进入项目目录
cd qbin
# 启动服务
docker-compose up -d
完成后，访问 http://localhost:8000 即可使用 QBin 服务，所有配置已在 docker-compose.yml 中预设好。
🐋 Docker 部署
# 拉取最新镜像
docker pull naiher/qbin:latest
# 启动容器
docker run -it -p 8000:8000 \
-e JWT_SECRET="your_jwt_secret" \
-e ADMIN_PASSWORD="qbin" \
-e ADMIN_EMAIL="admin@qbin.github" \
-e DB_CLIENT="sqlite" \
-e ENABLE_ANONYMOUS_ACCESS="1" \
-v ~/qbin-data:/app/data \
naiher/qbin
启动后，访问 http://localhost:8000 即可使用 QBin 服务。
☁️ Deno Deploy 云端部署
无需服务器，快速部署到 Deno 云平台：
- 准备一个 PostgreSQL 数据库
- Fork QBin 项目仓库
- 登录/注册 Deno Deploy
- 创建新项目：https://dash.deno.com/new_project
- 选择您 Fork 的项目，填写项目名称（关系到自动分配的域名）
- Entrypoint 填写
index.ts，其他字段留空 - 配置环境变量（详见下方环境变量说明）
- 点击 Deploy Project
- 部署成功后，点击生成的域名即可使用
- 部署完成后配置环境变量：
- 在 Project 的 Settings 中找到 Environment Variables
- 点击 Add Variable 添加必要的环境变量
- 自定义域名（可选）：
- 在 Project 的 Settings 中设置自定义二级域名或绑定自己的域名
- 在 Project 的 Settings 中设置自定义二级域名或绑定自己的域名
注意：使用 Deno 部署需要提前准备好 PostgreSQL 数据库。
🛢 数据库准备
Deno Deploy部署方式需要手动创建 PostgreSQL 数据库。如果你没有，那么可以使用以下几个提供免费方案的服务商：
| 服务商 | 免费方案 | 特点 |
|---|---|---|
| Render | 免费 10 GB 空间 | 与 Render 应用集成方便 |
| Aiven | 免费 5 GB 空间 | 稳定可靠，简单易用 |
| Neon | 免费 0.5 GB 空间 | 弹性扩展，零停机时间，开发者友好 |
🖥️ Deno CIL 本地部署
适合开发环境和本地测试，快速启动和调试：
Windows PowerShell 安装 Deno:
irm https://deno.land/install.ps1 | iex
Mac/Linux 安装 Deno:
curl -fsSL https://deno.land/install.sh | sh
克隆项目:
# 克隆项目仓库
git clone https://github.com/Quick-Bin/qbin.git
# 进入项目目录
cd qbin
启动项目:
deno run -NER --allow-ffi --allow-sys --unstable-kv --unstable-broadcast-channel index.ts
环境变量配置
在项目根目录 将.env.template 重命名为 .env 文件，并设置必要的环境变量（参考环境变量配置说明）：
ENABLE_ANONYMOUS_ACCESS=1 # 匿名访问，默认开启，0表示关闭, 支持共享编辑
ADMIN_EMAIL=admin@qbin.github # 管理员邮箱（必选）
ADMIN_PASSWORD=qbin # 管理员密码（必选）
DB_CLIENT=postgres # 选择数据库，支持 postgres、sqlite
DATABASE_URL=postgresql://user:password@host:5432/database
JWT_SECRET=your_jwt_secret # JWT密钥，用于加密验证（建议修改）
完成部署后，访问 http://localhost:8000 即可使用 QBin 服务。
⚙️ 环境变量配置说明
基础配置
| 环境变量 | 类型 | 描述 | 示例 |
|---|---|---|---|
ADMIN_PASSWORD | 必选 | 管理员访问密码 | qbin |
ADMIN_EMAIL | 必选 | 管理员邮箱地址 | admin@qbin.github |
DATABASE_URL | 必选 | PostgreSQL 数据库连接 URL | postgresql://user:password@host:5432/database |
JWT_SECRET | 必选 | JWT 签名密钥（建议使用随机字符串） | XTV0STZzYFxxxxxxxxxx5ecm50W04v |
PORT | 可选 | 服务访问端口，默认 8000 | 8000 |
ENABLE_ANONYMOUS_ACCESS | 可选 | 匿名访问, 支持共享编辑 | 1 |
TOKEN_EXPIRE | 可选 | 令牌有效期(秒)，默认一年 | 31536000 |
MAX_UPLOAD_FILE_SIZE | 可选 | 最大上传文件大小(字节)，默认 50MB | 52428800 |
DENO_KV_PROJECT_ID | 可选 | Deno KV 项目 ID，默认为空 | xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
DENO_KV_ACCESS_TOKEN | 可选 | Deno KV 项目访问令牌，默认为空 | `` |
社交登录配置（可选）
GitHub OAuth 配置
| 环境变量 | 类型 | 描述 | 示例 |
|---|---|---|---|
GITHUB_CLIENT_ID | 可选 | GitHub OAuth 应用客户端 ID | Ovxxxxxxxxxfle8Oyi |
GITHUB_CLIENT_SECRET | 可选 | GitHub OAuth 应用客户端密钥 | 56ab9xxxxxxxxxxxxxx4012184b426 |
GITHUB_CALLBACK_URL | 可选 | GitHub OAuth 回调地址 | http://localhost:8000/api/login/oauth2/callback/github |
Google OAuth 配置
| 环境变量 | 类型 | 描述 | 示例 |
|---|---|---|---|
GOOGLE_CLIENT_ID | 可选 | Google OAuth 应用客户端 ID | 84932xxxxx-gbxxxxxxxxxxxxjg8s3v.apps.googleusercontent.com |
GOOGLE_CLIENT_SECRET | 可选 | Google OAuth 应用客户端密钥 | GOCSPX-xxxxxxxxxxxxxxxxxxxx |
GOOGLE_CALLBACK_URL | 可选 | Google OAuth 回调地址 | http://localhost:8000/api/login/oauth2/callback/google |
Microsoft OAuth 配置
| 环境变量 | 类型 | 描述 | 示例 |
|---|---|---|---|
MICROSOFT_CLIENT_ID | 可选 | Microsoft OAuth 应用客户端 ID | a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6 |
MICROSOFT_CLIENT_SECRET | 可选 | Microsoft OAuth 应用客户端密钥 | abC8Q~xxxxxxxxxxxxxxxxxxxxxxxxxxxx |
MICROSOFT_CALLBACK_URL | 可选 | Microsoft OAuth 回调地址 | http://localhost:8000/api/login/oauth2/callback/microsoft |
Custom OAuth 配置
| 环境变量 | 类型 | 描述 | 示例 |
|---|---|---|---|
OAUTH_CLIENT_ID | 可选 | OAuth 应用的客户端标识符 | V4HmbQixxxxxxxxxxxxCJ2CVypqL |
OAUTH_CLIENT_SECRET | 可选 | OAuth 应用的客户端密钥 | hZtE3cxxxxxxxxxxxxxkZ0al01Hi |
OAUTH_AUTH_URL | 可选 | 授权端点 URL | https://provider.example.com/oauth2/authorize |
OAUTH_TOKEN_URL | 可选 | 令牌端点 URL | https://provider.example.com/oauth2/token |
OAUTH_CALLBACK_URL | 可选 | 认证成功后的回调地址 | http://localhost:8000/api/login/oauth2/callback/custom |
OAUTH_SCOPES | 可选 | 请求的权限范围，以空格分隔 | user:profile |
OAUTH_USER_INFO_URL | 可选 | 获取用户信息的 API 端点 | https://provider.example.com/api/user |
🔧 常见问题与故障排除
-
数据库连接失败
- 检查 DATABASE_URL 格式是否正确
- 确认数据库服务是否已启动
- 验证用户名密码是否正确
- 检查防火墙是否允许连接
-
部署成功但无法访问
- 检查端口是否被其他程序占用
- 确认防火墙是否允许该端口访问
- 检查 Deno Deploy 日志查看错误信息
-
社交登录无法使用
- 确认 OAuth 配置信息是否正确
- 检查回调 URL 是否与应用配置一致
- 确认已在对应平台启用了正确的 OAuth 权限
📚 更多信息
有关本项目的更多详细说明、API 文档和高级配置，请参考 完整文档。
如有任何问题，欢迎 提交 Issue 。