StarlensStarlens进入工作台

部署方式

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

Starlens 部署方式图，展示本地开发、Docker 自托管和 Node.js 自托管运行时与共享依赖之间的关系。
这张图强调三种运行路径复用同一套代码、数据库模式和认证配置，只是运行环境不同。

本地开发

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

常用命令：

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

推荐 .env 模板：

AUTH_SECRET="replace-with-random-secret"
NEXTAUTH_URL="http://localhost:3000"
AUTH_GITHUB_ID="github-client-id"
AUTH_GITHUB_SECRET="github-client-secret"
DATABASE_URL="postgres://starlens:starlens@localhost:54329/starlens_dev"
TOKEN_ENCRYPTION_SECRET="replace-with-random-32-byte-secret"
SYSTEM_AI_API_KEY=""
SYSTEM_AI_BASE_URL=""
SYSTEM_AI_MODEL=""
SYSTEM_AI_PROVIDER_TYPE="openai_compatible"
SYSTEM_AI_ENABLED="true"
SYSTEM_AI_FALLBACK_MODEL=""
SYSTEM_AI_EXTRA_HEADERS=""

本地 GitHub OAuth 回调地址应配置为：

http://localhost:3000/api/auth/callback/github

Node.js 自托管

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

基础流程：

  1. 在服务器准备 Node.js、pnpm 和数据库连接。
  2. 配置生产环境变量。
  3. 构建应用。
  4. 运行 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对外访问地址，例如 https://starlens.example.com
DATABASE_URLPostgreSQL 连接串；1Panel 同网络容器可使用 1Panel-postgresql:5432
AUTH_SECRETNextAuth 会话密钥
AUTH_GITHUB_IDGitHub OAuth Client ID
AUTH_GITHUB_SECRETGitHub OAuth Client Secret
TOKEN_ENCRYPTION_SECRETGitHub 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.example.com.conf
docker exec 1Panel-openresty nginx -t
docker exec 1Panel-openresty nginx -s reload

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

A  starlens  <SERVER_PUBLIC_IP>

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

DOMAIN=starlens.example.com PUBLIC_IP=<SERVER_PUBLIC_IP> 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 指向正确环境，避免把开发迁移误打到生产库。

DBA 脚本(管理员操作)

部分数据库变更属于 DBA 级操作(创建角色、行级安全策略),需要 CREATEROLE 权限,应用迁移用户不具备。这类操作独立放在 apps/web/dba/ 目录,由数据库超管在首次部署或环境初始化时执行一次,不随 drizzle-kit migrate 自动运行。

当前包含:

  • 0006_ai_readonly_role_and_rls.sql —— 为 AI Agent 的自由 SQL 检索工具建立 starlens_ai_readonly 只读角色和 RLS 策略。对应的 drizzle 迁移 0006 已置为空操作占位,仅维持迁移序号一致。

执行方式(用数据库超管账号,脚本幂等可重复执行):

# 生产 / 自托管(PostgreSQL 在容器内)
docker cp apps/web/dba/0006_ai_readonly_role_and_rls.sql <pg容器>:/tmp/0006.sql
docker exec <pg容器> psql -U <超管用户> -d <库名> -v ON_ERROR_STOP=1 -f /tmp/0006.sql

# 本地开发
psql -U postgres -d starlens_dev -v ON_ERROR_STOP=1 \
  -f apps/web/dba/0006_ai_readonly_role_and_rls.sql

新环境部署顺序:先用超管执行 dba/ 下的脚本,再跑 drizzle 迁移,最后启动 Web 服务。若跳过 DBA 脚本,应用本身可正常启动,但 AI Agent 的自由 SQL 检索功能会因角色不存在而报错。

AI 功能启用

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

启用前确认：

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

CLI / Agent / MCP 接入

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

Agent runtime 示例：

STARLENS_SKILL_FILE="/path/to/starlens/skills/starlens/SKILL.md"
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。