> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 通用安装

> Console 进程、数据库、对象存储与反向代理

本页是所有执行后端共用的底座；后端专属配置见各自页面。

## 启动 Console

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
git clone <starforge 仓库> && cd starforge
uv sync
uv run forge-console serve --port 8080 --serve    # --serve 绑定 0.0.0.0
```

配置统一走环境变量（前缀 `FORGE_`）或仓库根 `.env`（根目录 `.env.example` 是带注释的全量模板）。

## 核心配置

| 环境变量                                                            | 说明                                                  |
| --------------------------------------------------------------- | --------------------------------------------------- |
| `FORGE_DEFAULT_FLEET_KIND`                                      | `local` \| `node` \| `kuberay` \| `slurm`           |
| `FORGE_WEB_JWT_SECRET`                                          | **必设**固定强随机串；缺省随机生成会导致重启全员掉线、多副本 token 互不通用         |
| `FORGE_PUBLIC_URL`                                              | 对外可达地址（OIDC 回调 / CLI 授权用）                           |
| `FORGE_INGEST_URL`                                              | 训练容器回传指标的地址；**必须是集群网内可达的 console URL**，勿填 127.0.0.1 |
| `FORGE_ALLOWED_IMAGE_REGISTRIES`                                | 用户 `--image` 允许的仓库主机，逗号分隔。空：一等框架覆盖不限制，**自定义镜像拒绝**   |
| `FORGE_IMAGE_VERL` / `FORGE_IMAGE_TRL` / `FORGE_IMAGE_OPENRLHF` | 这些框架的默认 OCI 镜像（部署工件；catalog 不内嵌引用）                  |
| `FORGE_DB_PATH` / `FORGE_DB_URL`                                | 默认 SQLite（`.forge/web.db`）；生产可切 PostgreSQL          |
| `FORGE_REDIS_URL`                                               | 多副本部署强烈建议：token 即时吊销、分布式限流、一致性                      |
| `FORGE_TIMEZONE`                                                | 服务级时区（时段窗口与日报边界）                                    |

## 对象存储（MinIO / S3）

数据集、作业包分发（kuberay 必需）、产物归档共用一套：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
FORGE_S3_ENDPOINT=https://minio.internal
FORGE_S3_ACCESS_KEY=…
FORGE_S3_SECRET_KEY=…
FORGE_S3_BUCKET=starforge
```

作业侧永远只拿**预签名 URL**，不持有存储凭据。

## 反向代理（nginx）

`deploy/nginx.conf.example` 提供模板，要点：

* `/api` 关闭代理缓冲（SSE 日志流）；
* `/docs` 反代 Mintlify 托管站（见 `mintlify/README.md`）；
* WebSocket / 长连接超时放宽。

## 数据库迁移

服务启动自动执行 Alembic 迁移；手动操作：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv run alembic upgrade head
```

## 首个管理员

全新部署第一位用户经 `/api/auth/setup` 创建（控制台首次访问引导），或本地账号体系下由 CLI `sf admin user-add` 补充。接入 OIDC 见[鉴权与账号](/zh-Hans/ops/auth)。

<Tip>
  上线前跑一遍 [E2E 闭环](/zh-Hans/ops/e2e-testing)：一条命令验证「提交 → 调度 → 容器 → 回传」全链路配置正确。
</Tip>