部署方式

Starlens 可以在本地开发环境运行，也可以部署到 Vercel 或自托管环境。部署前需要准备 PostgreSQL 数据库、GitHub OAuth 应用和加密密钥。如果要启用 AI，还需要配置至少一个 AI Provider。

本地开发

准备 Node.js、pnpm 和 PostgreSQL。
在仓库根目录创建 .env，写入数据库连接串和 GitHub OAuth 配置。
安装依赖后执行数据库迁移。
启动 Web 应用并访问本地地址。

常用命令：

corepack pnpm install
corepack pnpm db:migrate:local
corepack pnpm dev

Vercel 部署

Vercel 部署适合希望快速上线 Web 应用的场景。你需要在 Vercel 项目环境变量中配置数据库连接串、NextAuth 密钥和 GitHub OAuth 凭据。

推荐变量：

变量	必填	用途
`DATABASE_URL`	是	PostgreSQL 连接串，推荐使用托管 PostgreSQL 或 Neon
`AUTH_SECRET`	是	NextAuth 会话密钥
`NEXTAUTH_URL`	是	线上站点地址
`AUTH_GITHUB_ID`	是	GitHub OAuth Client ID
`AUTH_GITHUB_SECRET`	是	GitHub OAuth Client Secret
`TOKEN_ENCRYPTION_SECRET`	是	加密 GitHub token、AI key 和额外 header
`SYSTEM_AI_API_KEY`	否	系统级默认 AI Provider 密钥，用户未配置默认 Provider 时回退使用
`SYSTEM_AI_BASE_URL`	否	系统级默认 OpenAI-compatible Base URL
`SYSTEM_AI_MODEL`	否	系统级默认模型名称

Vercel 上线流程：

创建 Vercel 项目并指向仓库。
配置 Production、Preview 和 Development 环境变量。
在 GitHub OAuth App 中新增生产回调地址。
执行数据库迁移。
部署后访问 /docs、/app 和 /api/search 做基础检查。

生产 GitHub OAuth 回调地址示例：

https://your-vercel-domain.vercel.app/api/auth/callback/github

自托管部署

自托管适合希望完全控制运行环境和数据库的场景。你可以把 Web 应用部署到自己的服务器，并连接自管 PostgreSQL。

基础流程：

在服务器准备 Node.js、pnpm 和数据库连接。
配置生产环境变量。
构建应用。
运行 Next.js 服务，并通过反向代理暴露 HTTPS 域名。

corepack pnpm install --frozen-lockfile
corepack pnpm build
corepack pnpm --filter @starlens/web start

反向代理需要转发 HTTPS 请求到 Next.js 服务，并保持 NEXTAUTH_URL 与公网域名一致。建议在代理层开启 HTTPS、HTTP/2、压缩和基础访问日志。

Docker 自托管

仓库内提供 Docker 部署配置，适合 1Panel、OpenResty 和自管 PostgreSQL 的服务器。默认宿主机端口使用 3333，容器内仍使用 Next.js 默认的 3000。

准备生产环境变量：

cp deploy/.env.production.example deploy/.env.production

至少填写：

变量	说明
`NEXTAUTH_URL`	对外访问地址，例如 `http://your-server-ip:3333` 或正式 HTTPS 域名
`DATABASE_URL`	PostgreSQL 连接串；1Panel 同网络容器可使用 `1Panel-postgresql-xIiE:5432`
`AUTH_SECRET`	NextAuth 会话密钥
`AUTH_GITHUB_ID`	GitHub OAuth Client ID
`AUTH_GITHUB_SECRET`	GitHub OAuth Client Secret
`TOKEN_ENCRYPTION_SECRET`	GitHub token、AI key 和额外 header 的加密密钥

启动前先执行迁移：

docker compose -f deploy/docker-compose.yml --profile migrate run --rm starlens-migrate

启动 Web 服务：

docker compose -f deploy/docker-compose.yml up -d --build starlens-web

服务默认暴露在：

http://服务器地址:3333

如果前面有 OpenResty 或 1Panel 网站反代，代理目标应指向 127.0.0.1:3333，并把 NEXTAUTH_URL 改成最终 HTTPS 域名。GitHub OAuth App 的回调地址必须同步改为：

{NEXTAUTH_URL}/api/auth/callback/github

OpenResty 与 HTTPS

1Panel/OpenResty 场景下可以复用仓库里的反代模板：

cp deploy/openresty-starlens.conf.example /opt/1panel/www/conf.d/starlens.520ai.xin.conf
docker exec 1Panel-openresty-oXOm nginx -t
docker exec 1Panel-openresty-oXOm nginx -s reload

正式域名上线前，需要在 Cloudflare 创建 DNS 记录：

A  starlens  服务器公网 IP

DNS 生效后，推荐用 Let’s Encrypt/acme.sh 签发免费证书并自动续期：

DOMAIN=starlens.520ai.xin PUBLIC_IP=140.238.61.108 bash deploy/issue-letsencrypt.sh

acme.sh 会安装 cron 任务自动续期。证书路径生成后，在 OpenResty 配置中启用 HTTPS server，并把 HTTP 站点的 / 访问改为 301 跳转到 HTTPS。

数据库迁移

Starlens 使用 Drizzle 管理 PostgreSQL schema。首次上线或 schema 变更后执行：

corepack pnpm db:migrate

本地开发可以使用：

corepack pnpm db:migrate:local

Neon 环境可以使用：

corepack pnpm db:migrate:neon

迁移前建议确认目标 DATABASE_URL 指向正确环境，避免把开发迁移误打到生产库。

AI 功能启用

AI 功能不是启动 Web 应用的硬依赖。上线后可以在设置页创建用户级 AI Provider，也可以通过环境变量提供系统级默认 Provider。

启用前确认：

Provider 的 API Key 可用。
Base URL 包含正确协议和路径。
模型 ID 是真实可调用的模型 ID。
如果使用网关，额外 header 已正确配置。
设置页中的 Provider 验证结果为 success。

CLI / Agent / MCP 接入

CLI、Agent HTTP tools 和 MCP 不需要单独部署公网服务。它们通过个人 API Token 调用当前 Starlens 站点。

Agent runtime 示例：

STARLENS_TOKEN="stl_xxx"
STARLENS_API_BASE_URL="https://your-starlens.example.com"

本地 MCP 示例：

STARLENS_TOKEN="stl_xxx" \
STARLENS_API_BASE_URL="https://your-starlens.example.com" \
corepack pnpm mcp:start

如果 API 部署在内网，Agent runtime、CLI 或 IDE 所在机器必须能访问 STARLENS_API_BASE_URL。

部署检查

GitHub OAuth 回调地址需要和线上域名一致。
数据库迁移需要在首次上线前执行。
如果启用 AI 功能，需要在设置页配置对应 Provider。
如果要给 CLI 使用，需要在 Tokens 页面创建个人 API Token。
/api/sync 能成功触发同步，并在 GitHub 速率限制内完成。
/api/search 能返回当前用户的数据，且不会返回其他用户仓库。
Token 撤销后，旧 Bearer Token 不能继续访问 API。
生产环境不要暴露 .env、数据库连接串或 AI API Key。