文档/自托管指南

自托管指南

使用产品当前优化的单节点部署形态在你自己的基础设施上运行 VibeBasket：一个应用进程、一个 SQLite 数据库、可选 OAuth，以及可选的加密备份存储。

Docker（推荐）

这是自托管 VibeBasket 最简单的方式。镜像使用基于 Node.js 22 Alpine 的轻量 multi-stage build。SQLite 数据库文件持久化到命名 Docker volume 中，因此容器重启或升级后数据仍会保留。

步骤 1 — 克隆并配置

git clone https://github.com/mhmtayberk/VibeBasket.git
cd VibeBasket

# Copy the example env file and fill in your values
cp .env.example .env

步骤 2 — 用 Docker Compose 启动

docker compose up -d

# View logs
docker compose logs -f web

步骤 3 — 初始化目录数据

# Run the catalog sync inside the running container
docker compose exec web node scripts/catalog-sync.mjs

升级

git pull
docker compose up -d --build

Helm (Kubernetes)

charts/vibebasket/ 中提供了完整的 Helm chart。该 chart 会部署单副本 Deployment、ClusterIP Service、可选 Ingress，以及用于 SQLite 数据库的 PersistentVolumeClaim。非敏感运行时值应放在 .Values.env 下，而 AUTH_SECRET 与 OAuth client secret 这类敏感值应放在 .Values.secretEnv 下，或放入已有 Kubernetes Secret 中。

git clone https://github.com/mhmtayberk/VibeBasket.git
cd VibeBasket

helm install vibebasket ./charts/vibebasket \
  --set env.NEXTAUTH_URL=https://vibebasket.example.com \
  --set secretEnv.AUTH_SECRET=$(openssl rand -base64 32) \
  --set env.AUTH_GITHUB_ID=your-client-id \
  --set secretEnv.AUTH_GITHUB_SECRET=your-client-secret \
  --set env.AUTH_GITHUB_ENABLED=true \
  --set persistence.size=5Gi

# Or install with a custom values file
helm install vibebasket ./charts/vibebasket -f my-values.yaml

手动安装

需要 Node.js >=20 与 pnpm >=9。适用于虚拟机、裸金属服务器，或无法运行 Docker 的平台。

git clone https://github.com/mhmtayberk/VibeBasket.git && cd VibeBasket
cp .env.example .env          # fill in values (see below)
pnpm install --frozen-lockfile
pnpm run build
node scripts/catalog-sync.mjs # seed the database
pnpm --filter web start        # production server on :3000

环境变量

OAuth 回调 URL

启用 OAuth 身份验证时，必须在每个提供方的开发者控制台中配置准确的重定向回调 URL：

GitHub

${NEXTAUTH_URL}/api/auth/callback/github

Google

${NEXTAUTH_URL}/api/auth/callback/google

Apple

${NEXTAUTH_URL}/api/auth/callback/apple

Microsoft Entra ID

${NEXTAUTH_URL}/api/auth/callback/microsoft-entra-id

本地开发时，将 ${NEXTAUTH_URL} 替换为 http://localhost:3000。

永远不要提交 .env 文件。.env .gitignore 中。对于 Docker 部署，请通过环境变量传递密钥，或使用 Docker secrets。

如果你把 VibeBasket 运行在 Cloudflare 后面，请保持应用安全响应头开启，并为该站点关闭会注入脚本的 edge 功能，除非你已经明确为其做了兼容设计。实际操作上，这意味着关闭 Browser Insights、Rocket Loader 以及会注入内联或第三方脚本的 Speed Brain / speculative prefetch，否则站点会按设计记录 CSP 违规。

变量	必需	说明
DATABASE_URL	必需	SQLite connection string. Use file:/data/vibebasket.db for Docker (volume mount) or an absolute path for manual installs.
AUTH_SECRET	必需	Random 32-byte secret used to sign Next-Auth session tokens. Generate with: openssl rand -base64 32
NEXTAUTH_URL	必需	The public canonical URL of your deployment, e.g. https://vibebasket.example.com. Required for OAuth redirects.
AUTH_TRUST_HOST	可选	Set to true when running behind a reverse proxy such as Coolify, Nginx, or Cloudflare. Strongly recommended for production OAuth callback reliability.
AUTH_GITHUB_ID / SECRET	可选	GitHub OAuth App credentials. Set AUTH_GITHUB_ENABLED=true to enable.
AUTH_GOOGLE_ID / SECRET	可选	Google OAuth credentials. Set AUTH_GOOGLE_ENABLED=true to enable.
AUTH_APPLE_ID / SECRET	可选	Apple Sign-In credentials. Set AUTH_APPLE_ENABLED=true to enable.
AUTH_MICROSOFT_ENTRA_ID_ID / SECRET	可选	Microsoft Entra ID (Azure AD) credentials. Set AUTH_MICROSOFT_ENTRA_ID_ENABLED=true. Uses /common/ endpoint by default.
ADMIN_OAUTH_EMAILS	可选	Comma-separated list of admin emails. Access is granted only when the OAuth account email is allowlisted and verified.
TRUST_PROXY	可选	Set to true when running behind Cloudflare, Nginx, or another trusted reverse proxy. Proxy IP headers are ignored otherwise.
CATALOG_REFRESH_TOKEN	可选	Optional token required for authenticated production callers that use /api/catalog?refresh=1.
BACKUP_STORAGE_BACKEND	可选	Backup storage backend: local, s3, r2, spaces, azure, or gcs. Defaults to local. Can also be set via admin panel.
BACKUP_S3_* / R2_* / SPACES_*	可选	S3-compatible storage credentials (endpoint, region, bucket, access key, secret key). Covers AWS S3, Cloudflare R2, and DigitalOcean Spaces.
BACKUP_AZURE_CONNECTION_STRING / CONTAINER	可选	Azure Blob Storage connection string and container name.
BACKUP_GCS_BUCKET / PROJECT_ID	可选	Google Cloud Storage bucket name and GCP project ID.

Bundle 生命周期与清理

匿名 bundle 会在 48 小时后过期。已注册用户的 bundle 会保留 365 天。平台会定期清理过期 bundle 与陈旧 session token。管理员可在管理面板的 System Health 区域手动触发强制清理。

管理面板

/admin 管理面板提供目录同步控制、备份管理、FTS5 索引健康检查、数据库完整性诊断、强制清理工具、用户概览遥测以及管理员邮箱配置。访问受 ADMIN_OAUTH_EMAILS 环境变量控制。

Helm 部署

charts/vibebasket/ 下提供 Kubernetes 部署用 Helm chart。该 chart 包含 Deployment、Service、Ingress，以及 SQLite 存储所需的 PersistentVolumeClaim。

$ helm install vibebasket ./charts/vibebasket \

--set env.NEXTAUTH_URL=https://vibebasket.example.com \

--set secretEnv.AUTH_SECRET=<generated-secret>

为防止更新期间 SQLite 损坏，部署使用 strategy: Recreate 。Pod securityContext 以非 root 的 1001 用户运行，并移除全部 capabilities。生产环境 secret 应通过 existingSecret 提供，而不是直接写入 values。

在公开域名之前，请先完成仓库中 docs/PRODUCTION_READINESS_CHECKLIST.md 的生产就绪检查。

SQLite WAL 模式

VibeBasket 在启动时会启用 SQLite WAL（Write-Ahead Logging）模式。这允许在写入期间进行并发读取，也是目录同步流程所必需的。不要把数据库文件挂载到网络文件系统（NFS、CIFS）上，因为 WAL 锁依赖本地操作系统原语。如果你运行多个 Node.js 副本，请使用负载均衡把所有写入路由到单个实例，或迁移到 Turso 这类远程数据库。