diff --git a/README.md b/README.md index 4f68bf5b..fb10df42 100644 --- a/README.md +++ b/README.md @@ -40,9 +40,7 @@ - [功能特性](#功能特性) - [界面预览](#界面预览) - [快速开始](#快速开始) -- [配置说明](#配置说明) -- [项目结构](#项目结构) -- [开发指南](#开发指南) +- [文档与延伸阅读](#文档与延伸阅读) - [License](#license) --- @@ -141,228 +139,35 @@ ## 快速开始 -### 环境要求 - -| 依赖 | 版本 | 说明 | -| ---------- | ---- | -------------------------------------- | -| Node.js | 22+ | 推荐使用 [pnpm](https://pnpm.io/) 管理 | -| PostgreSQL | 16+ | 生产环境推荐（默认） | -| SQLite | 最新 | 本地开发可选（通过 `DB_TYPE=sqlite`） | - -### Docker 部署 (推荐) +最小可用启动流程如下： ```bash -# 1. 克隆项目 git clone https://github.com/g1331/AutoRouter.git cd AutoRouter - -# 2. 配置环境变量 cp .env.example .env -# 编辑 .env 文件，设置 ADMIN_TOKEN 和 ENCRYPTION_KEY - -# 3. 启动服务 +# 编辑 .env：至少设置 ADMIN_TOKEN 与 ENCRYPTION_KEY docker compose up -d - -# 4. 默认访问 http://localhost:3331 -# 如果你修改了 .env 中的 PORT，请改用对应端口访问 -``` - -### 版本发布与个人部署 - -仓库默认的 GitHub Actions 主线负责校验、构建镜像和创建 GitHub Release。个人服务器部署改为手动触发的独立流程，只消费已经发布的镜像。 - -**1. 正式版本发布** - -```bash -# 1. 确认 master 已通过 Verify workflow - -# 2. 更新 package.json 中的 version - -# 3. 创建并推送标签 -git tag v1.0.0 -git push origin v1.0.0 -``` - -推送标签后，`Release` workflow 会自动校验标签与版本号一致、构建 GHCR 镜像并创建 GitHub Release。 - -**2. 配置个人部署 Secrets** - -在仓库 Settings → Secrets and variables → Actions 中添加： - -| Secret | 说明 | -| ----------------- | ----------------------------------------- | -| `SERVER_HOST` | 服务器 IP 或域名 | -| `SERVER_USER` | SSH 用户名 | -| `SSH_PRIVATE_KEY` | SSH 私钥内容 | -| `SERVER_PORT` | SSH 端口 (可选，默认 22) | -| `DEPLOY_DIR` | 部署目录 (可选，默认 /opt/autorouter) | -| `ADMIN_TOKEN` | 管理后台令牌，会在部署时写入服务器 `.env` | - -**3. 服务器初始化** - -```bash -# 创建部署目录 -mkdir -p /opt/autorouter && cd /opt/autorouter - -# 下载 docker-compose.yml -curl -O https://raw.githubusercontent.com/g1331/AutoRouter/v1.0.0/docker-compose.yml - -# 创建 .env 文件 (参考 .env.example) -# 其中 AUTOROUTER_IMAGE 需要填写目标发布镜像，例如 ghcr.io/g1331/autorouter:v1.0.0 -nano .env - -# 首次启动 -docker compose up -d -``` - -**4. 手动触发个人部署** - -```bash -# 在 GitHub Actions 页面手动运行 Personal Deploy -# image_ref 可填写 v1.0.0、完整 ghcr.io 镜像地址或 sha256 digest -# confirm_release_id 填写对应的发布标签，例如 v1.0.0 -``` - -### 本地开发 - -README 当前提供两种运行模式，但数据库准备方式不同，请不要直接复制 `.env.example` 后原样执行。 - -#### 方案一：本地 PostgreSQL - -```bash -# 1. 克隆项目 -git clone https://github.com/g1331/AutoRouter.git -cd AutoRouter - -# 2. 复制环境变量 -cp .env.example .env.local - -# 3. 把 .env.local 中的 DATABASE_URL 改成宿主机地址 -# 例如： -# DATABASE_URL=postgresql://autorouter:password@localhost:5432/autorouter - -# 4. 生成加密密钥 (填入 .env.local) -node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" - -# 5. 安装依赖 -pnpm install - -# 6. 推送 PostgreSQL Schema -pnpm db:push - -# 7. 启动开发服务器 -pnpm dev -``` - -启动后访问 ，使用 `ADMIN_TOKEN` 登录。 - -#### 方案二：本地 SQLite - -运行时代码支持 SQLite，本地快速试跑时可以这样配置： - -```bash -# 1. 复制环境变量 -cp .env.example .env.local - -# 2. 在 .env.local 中设置 -# DB_TYPE=sqlite -# SQLITE_DB_PATH=./data/dev.sqlite - -# 3. 生成加密密钥 (填入 .env.local) -node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" - -# 4. 安装依赖 -pnpm install - -# 5. 启动开发服务器 -pnpm dev +# 默认访问 http://localhost:3331 ``` -注意：仓库当前封装的 Drizzle CLI 脚本默认面向 PostgreSQL。SQLite 运行时是受支持的，但 README 不再把 `pnpm db:push` 宣传为 SQLite 的通用初始化命令。 - ---- +环境要求：Node.js 22+（源码构建场景）、PostgreSQL 16（默认，生产推荐）；本地开发可改用 SQLite。 -## 配置说明 - -### 环境变量 (`.env` 或 `.env.local`) - -| 变量 | 必填 | 说明 | -| --------------------------- | :------: | ------------------------------------------------------------------------------------- | -| `DATABASE_URL` | 条件必填 | PostgreSQL 模式下必填；未设置 `DB_TYPE` 时，只要提供它就会自动选择 PostgreSQL | -| `DB_TYPE` | | 数据库类型，支持 `postgres` 或 `sqlite`；未设置时会按 `DATABASE_URL` 是否存在自动判断 | -| `SQLITE_DB_PATH` | | SQLite 文件路径（`DB_TYPE=sqlite` 时使用） | -| `ENCRYPTION_KEY` | ✓\* | Fernet 加密密钥（与 `ENCRYPTION_KEY_FILE` 二选一） | -| `ENCRYPTION_KEY_FILE` | ✓\* | 从文件读取加密密钥（与 `ENCRYPTION_KEY` 二选一） | -| `ADMIN_TOKEN` | ✓ | 管理后台登录令牌 | -| `ALLOW_KEY_REVEAL` | | 是否允许展示完整 API Key，默认 `false` | -| `LOG_RETENTION_DAYS` | | 日志保留天数，默认 `90` | -| `LOG_LEVEL` | | 日志级别：`fatal` / `error` / `warn` / `info` / `debug` / `trace` | -| `DEBUG_LOG_HEADERS` | | 是否输出请求头调试日志，默认 `false` | -| `HEALTH_CHECK_INTERVAL` | | 上游健康检查间隔（秒），默认 `30` | -| `HEALTH_CHECK_TIMEOUT` | | 上游健康检查超时（秒），默认 `10` | -| `CORS_ORIGINS` | | CORS 白名单，逗号分隔 | -| `PORT` | | 服务端口，默认 `3000` | -| `RECORDER_ENABLED` | | 是否开启流量录制。代码默认关闭，仓库提供的 compose 默认开启 | -| `RECORDER_MODE` | | 录制模式：`all` / `success` / `failure` | -| `RECORDER_FIXTURES_DIR` | | 录制文件目录，默认 `tests/fixtures` | -| `RECORDER_REDACT_SENSITIVE` | | 是否脱敏录制内容。代码默认 `true`，但仓库提供的生产部署模板默认写入 `false` | +更完整的部署形态、版本发布、个人部署 secrets、源码本地开发、SQLite 切换流程，详见文档站 [部署指南](https://g1331.github.io/AutoRouter/guide/deployment/overview)。 --- -## 项目结构 - -| 目录 | 说明 | -| ------------------------------ | ------------------------------------------------------------------------------------------------------- | -| `src/app/api/proxy` | 代理入口，负责路径能力判定、候选集构建、故障转移和日志记录 | -| `src/app/api/admin` | 管理 API，包含 keys、upstreams、stats、logs、billing、compensation、health、circuit-breakers | -| `src/app/[locale]/(dashboard)` | 管理台页面，包含 dashboard、keys、logs、upstreams、settings、system/billing、system/header-compensation | -| `src/lib/services` | 核心业务服务，如负载均衡、熔断、健康检查、计费、日志、流量录制、会话亲和 | -| `src/lib/db` | 数据库访问与 schema，运行时支持 PostgreSQL / SQLite | -| `src/components` | 管理台组件与通用 UI 组件 | -| `tests` | 单元测试、组件测试、E2E、可访问性和视觉回归测试 | -| `drizzle` / `drizzle-sqlite` | PostgreSQL / SQLite 迁移产物 | -| `docs` / `openspec` | 补充文档与变更规格 | +## 文档与延伸阅读 ---- +| 主题 | 链接 | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 部署形态与快速开始 | [`guide/deployment`](https://g1331.github.io/AutoRouter/guide/deployment/overview) | +| 环境变量参考 | [`guide/deployment/env-reference`](https://g1331.github.io/AutoRouter/guide/deployment/env-reference) | +| GitHub Actions 部署 | [`guide/deployment/github-actions`](https://g1331.github.io/AutoRouter/guide/deployment/github-actions) | +| 管理后台使用指南 | [`guide/usage`](https://g1331.github.io/AutoRouter/guide/usage/admin-overview) | +| 整体架构与请求生命周期 | [`guide/architecture`](https://g1331.github.io/AutoRouter/guide/architecture/overview) | +| 测试策略与贡献规范 | [`guide/architecture/testing`](https://g1331.github.io/AutoRouter/guide/architecture/testing) · [`contributing`](https://g1331.github.io/AutoRouter/guide/architecture/contributing) | -## 开发指南 - -
-代码检查 - -```bash -pnpm lint # ESLint -pnpm format # Prettier -pnpm exec tsc --noEmit # Type check -``` - -
- -
-运行测试 - -```bash -pnpm test # Watch 模式 -pnpm test:run # 单次运行 -pnpm test:run --coverage # 覆盖率报告 -pnpm e2e # Playwright E2E -pnpm e2e:headed # 有界面模式运行 E2E -``` - -
- -
-数据库操作 - -```bash -pnpm db:generate # 生成迁移文件 -pnpm db:migrate # 执行迁移 -pnpm db:push # 推送 Schema 到数据库 -pnpm db:seed # 写入轻量示例数据 -pnpm db:studio # 打开 Drizzle Studio -``` - -
+文档结构、撰写背景与版本规划参见 [issue #167](https://github.com/g1331/AutoRouter/issues/167)。 --- diff --git a/README_EN.md b/README_EN.md index 3ee7d395..3a5db678 100644 --- a/README_EN.md +++ b/README_EN.md @@ -33,6 +33,8 @@ +> The full documentation site is maintained in Simplified Chinese. The English README covers the high-level overview, screenshots, and the minimal Docker quick start; for deployment, configuration, and architecture details please follow the doc-site links below or use your browser's translation feature. + --- ## Table of Contents @@ -40,9 +42,7 @@ - [Features](#features) - [Screenshots](#screenshots) - [Quick Start](#quick-start) -- [Configuration](#configuration) -- [Project Structure](#project-structure) -- [Development Guide](#development-guide) +- [Documentation](#documentation) - [License](#license) --- @@ -141,221 +141,35 @@ ## Quick Start -### Requirements - -| Dependency | Version | Notes | -| ---------- | ------- | --------------------------------------------------- | -| Node.js | 22+ | Recommend using [pnpm](https://pnpm.io/) | -| PostgreSQL | 16+ | Recommended for production (default) | -| SQLite | Latest | Optional for local development via `DB_TYPE=sqlite` | - -### Docker Deployment (Recommended) +Minimum start-up flow: ```bash -# 1. Clone the repository git clone https://github.com/g1331/AutoRouter.git cd AutoRouter - -# 2. Configure environment variables cp .env.example .env -# Edit .env file, set ADMIN_TOKEN and ENCRYPTION_KEY - -# 3. Start services -docker compose up -d - -# 4. Visit http://localhost:3331 by default -# If you changed PORT in .env, use that port instead -``` - -### Release And Personal Deployment - -The default GitHub Actions flow now handles verification, image publishing, and GitHub Releases. Personal server deployment is a separate manual workflow that only deploys images that have already been released. - -**1. Publish an official release** - -```bash -# 1. Ensure master has passed the Verify workflow - -# 2. Update the version in package.json - -# 3. Create and push the release tag -git tag v1.0.0 -git push origin v1.0.0 -``` - -After the tag is pushed, the `Release` workflow validates the tag, publishes the GHCR image, and creates the GitHub Release. - -**2. Configure personal deployment secrets** - -Add these secrets in Settings → Secrets and variables → Actions: - -| Secret | Description | -| ----------------- | -------------------------------------------------------------- | -| `SERVER_HOST` | Server IP or domain | -| `SERVER_USER` | SSH username | -| `SSH_PRIVATE_KEY` | SSH private key content | -| `SERVER_PORT` | SSH port, optional, default `22` | -| `DEPLOY_DIR` | Deploy directory, optional, default `/opt/autorouter` | -| `ADMIN_TOKEN` | Admin console token written to the server `.env` during deploy | - -**3. Initialize the server** - -```bash -mkdir -p /opt/autorouter && cd /opt/autorouter -curl -O https://raw.githubusercontent.com/g1331/AutoRouter/v1.0.0/docker-compose.yml -# Set AUTOROUTER_IMAGE in .env, for example ghcr.io/g1331/autorouter:v1.0.0 -nano .env +# Edit .env: at minimum set ADMIN_TOKEN and ENCRYPTION_KEY docker compose up -d +# Visit http://localhost:3331 by default ``` -**4. Trigger a personal deployment** - -```bash -# Run the Personal Deploy workflow from GitHub Actions -# image_ref may be a release tag, full ghcr.io image ref, or sha256 digest -# confirm_release_id must be the matching release tag, for example v1.0.0 -``` - -### Local Development - -Do not copy `.env.example` and run it unchanged. The repository supports two local runtime modes, and the database setup differs between them. - -#### Option 1: Local PostgreSQL - -```bash -# 1. Clone the repository -git clone https://github.com/g1331/AutoRouter.git -cd AutoRouter - -# 2. Copy environment variables -cp .env.example .env.local - -# 3. Change DATABASE_URL in .env.local to a host-local address -# For example: -# DATABASE_URL=postgresql://autorouter:password@localhost:5432/autorouter - -# 4. Generate encryption key (add to .env.local) -node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" - -# 5. Install dependencies -pnpm install - -# 6. Push PostgreSQL schema -pnpm db:push - -# 7. Start development server -pnpm dev -``` - -After starting, visit http://localhost:3000 and login with `ADMIN_TOKEN`. - -#### Option 2: Local SQLite - -The runtime supports SQLite for local sandboxing: - -```bash -# 1. Copy environment variables -cp .env.example .env.local - -# 2. Set these values in .env.local -# DB_TYPE=sqlite -# SQLITE_DB_PATH=./data/dev.sqlite - -# 3. Generate encryption key -node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" - -# 4. Install dependencies -pnpm install - -# 5. Start development server -pnpm dev -``` - -Note: the packaged Drizzle CLI scripts currently target PostgreSQL by default. SQLite is supported at runtime, but this README no longer claims that `pnpm db:push` is a general SQLite initialization flow. - ---- - -## Configuration - -### Environment Variables (`.env` or `.env.local`) - -| Variable | Required | Description | -| --------------------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------- | -| `DATABASE_URL` | Conditional | Required in PostgreSQL mode; when `DB_TYPE` is unset, providing this value makes the app choose PostgreSQL automatically | -| `DB_TYPE` | | Database backend: `postgres` or `sqlite`; when unset, the app auto-detects based on whether `DATABASE_URL` exists | -| `SQLITE_DB_PATH` | | SQLite file path (used when `DB_TYPE=sqlite`) | -| `ENCRYPTION_KEY` | Yes\* | Fernet key (either this or `ENCRYPTION_KEY_FILE`) | -| `ENCRYPTION_KEY_FILE` | Yes\* | Load Fernet key from file (either this or `ENCRYPTION_KEY`) | -| `ADMIN_TOKEN` | Yes | Admin console login token | -| `ALLOW_KEY_REVEAL` | | Allow revealing full API keys, default `false` | -| `LOG_RETENTION_DAYS` | | Request log retention days, default `90` | -| `LOG_LEVEL` | | Log level: `fatal`/`error`/`warn`/`info`/`debug`/`trace` | -| `DEBUG_LOG_HEADERS` | | Debug header logging switch, default `false` | -| `HEALTH_CHECK_INTERVAL` | | Upstream health check interval in seconds, default `30` | -| `HEALTH_CHECK_TIMEOUT` | | Upstream health check timeout in seconds, default `10` | -| `CORS_ORIGINS` | | CORS allowlist, comma-separated | -| `PORT` | | Service port, default `3000` | -| `RECORDER_ENABLED` | | Enable traffic recording. Code defaults to off, while the repository compose file enables it by default | -| `RECORDER_MODE` | | Recorder mode: `all` / `success` / `failure` | -| `RECORDER_FIXTURES_DIR` | | Fixture output directory, default `tests/fixtures` | -| `RECORDER_REDACT_SENSITIVE` | | Redact sensitive fields in fixtures. Code default is `true`, but the repository's production deployment template writes `false` | - ---- - -## Project Structure +Runtime requirements: Node.js 22+ (for source builds), PostgreSQL 16 (default, recommended for production); SQLite is supported for local development. -| Path | Purpose | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -| `src/app/api/proxy` | Proxy entrypoint handling path-capability matching, candidate construction, failover, and request logging | -| `src/app/api/admin` | Admin APIs for keys, upstreams, stats, logs, billing, compensation, health, and circuit breakers | -| `src/app/[locale]/(dashboard)` | Admin console pages including dashboard, keys, logs, upstreams, settings, `system/billing`, and `system/header-compensation` | -| `src/lib/services` | Core services such as load balancing, circuit breaker, health checking, billing, logging, traffic recording, and session affinity | -| `src/lib/db` | Database access and schema definitions with PostgreSQL / SQLite runtime support | -| `src/components` | Admin console components and shared UI primitives | -| `tests` | Unit, component, E2E, accessibility, and visual regression tests | -| `drizzle` / `drizzle-sqlite` | PostgreSQL / SQLite migration outputs | -| `docs` / `openspec` | Supporting documentation and change specifications | +For deployment topologies, release workflow, personal deployment secrets, source-based local development, and SQLite switching, see the [Deployment Guide](https://g1331.github.io/AutoRouter/guide/deployment/overview) on the docs site (Simplified Chinese; browser translation works for the prose sections, while code blocks remain in English). --- -## Development Guide +## Documentation -
-Code Checking - -```bash -pnpm lint # ESLint -pnpm format # Prettier -pnpm exec tsc --noEmit # Type check -``` - -
- -
-Running Tests +| Topic | Link | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Deployment topologies & quickstart | [`guide/deployment`](https://g1331.github.io/AutoRouter/guide/deployment/overview) | +| Environment variable reference | [`guide/deployment/env-reference`](https://g1331.github.io/AutoRouter/guide/deployment/env-reference) | +| GitHub Actions deployment | [`guide/deployment/github-actions`](https://g1331.github.io/AutoRouter/guide/deployment/github-actions) | +| Admin console usage | [`guide/usage`](https://g1331.github.io/AutoRouter/guide/usage/admin-overview) | +| Architecture & request lifecycle | [`guide/architecture`](https://g1331.github.io/AutoRouter/guide/architecture/overview) | +| Testing strategy & contributing | [`guide/architecture/testing`](https://g1331.github.io/AutoRouter/guide/architecture/testing) · [`contributing`](https://g1331.github.io/AutoRouter/guide/architecture/contributing) | -```bash -pnpm test # Watch mode -pnpm test:run # Single run -pnpm test:run --coverage # Coverage report -pnpm e2e # Playwright E2E -pnpm e2e:headed # Run E2E with visible browser -``` - -
- -
-Database Operations - -```bash -pnpm db:generate # Generate migration files -pnpm db:migrate # Apply migrations -pnpm db:push # Push schema to database -pnpm db:seed # Seed lightweight sample data -pnpm db:studio # Open Drizzle Studio -``` - -
+Documentation scope, background, and version planning are tracked in [issue #167](https://github.com/g1331/AutoRouter/issues/167). ---