+ 简体中文 | + 繁體中文 | + English | + Français | + 日本語 +
+ +Ce document explique aux développeurs comment exécuter et développer le projet new-api localement. + +## Prérequis + +- **Go**: 1.22+ (le projet utilise 1.25.1) +- **Bun**: Gestionnaire de paquets frontend (préféré à npm/yarn) +- **Database**: SQLite (par défaut) / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 +- **Docker** (optionnel): Pour l'environnement de développement conteneurisé + +## Démarrage Rapide + +### Méthode 1: Développement Local (Recommandé) + +> **Prérequis**: Puisque Go utilise `//go:embed` pour intégrer les fichiers frontend, vous devez compiler le frontend une fois avant le premier démarrage, sinon une erreur se produira. + +#### 1. Configuration Initiale + +```bash +# Compiler le frontend (générer le répertoire dist pour éviter l'erreur go:embed) +cd web/default +bun install +bun run build +cd ../.. + +``` + +#### 2. Démarrer le Backend + +```bash +# Installer les dépendances Go +go mod download + +# Démarrer le service backend (utilisant SQLite) +go run main.go +``` + +Le backend s'exécute par défaut sur `http://localhost:3000`, les données sont stockées dans `one-api.db` + +#### 3. Démarrer le Frontend + +```bash +# Entrer dans le répertoire frontend +cd web/default + +# Installer les dépendances +bun install + +# Démarrer le serveur de développement +bun run dev +``` + +Le serveur de développement frontend s'exécute sur `http://localhost:5173` et proxifie automatiquement les requêtes backend vers le port 3000. + +### Méthode 2: Utilisation du Makefile + +```bash +# Démarrer backend et frontend simultanément (Docker + serveur de développement frontend) +make dev + +# Démarrer uniquement le backend (Docker Compose) +make dev-api + +# Démarrer uniquement le frontend +make dev-web + +# Démarrer le frontend classique +make dev-web-classic +``` + +## Développement Frontend + +### Commandes Disponibles + +Dans le répertoire `web/default/`: + +```bash +bun run dev # Démarrer le serveur de développement (http://localhost:5173) +bun run build # Compilation de production +bun run preview # Prévisualiser la compilation de production +bun run typecheck # Vérification des types TypeScript +bun run lint # Vérification du code ESLint +bun run format # Formatage du code Prettier +bun run format:check # Vérifier le formatage du code +bun run i18n:sync # Synchroniser les traductions d'internationalisation +``` + +### Stack Technique + +- **React 19** + **TypeScript** +- **Rsbuild** - Outil de compilation +- **Base UI** - Bibliothèque de composants +- **Tailwind CSS** - Stylisation +- **TanStack Router** - Routage +- **TanStack Query** - Récupération de données +- **i18next** - Internationalisation (supporte en/zh/fr/ru/ja/vi) + +### Développement de l'Internationalisation + +Les fichiers de traduction sont situés dans `web/default/src/i18n/locales/{lang}.json`. Après avoir ajouté ou modifié des traductions, exécutez: + +```bash +bun run i18n:sync +``` + +## Développement Backend + +### Configuration de la Base de Données + +#### SQLite (Par Défaut) + +Aucune configuration nécessaire, exécutez simplement `go run main.go`. + +#### MySQL + +```bash +# Définir la variable d'environnement +export SQL_DSN="root:password@tcp(localhost:3306)/newapi" + +# Démarrer le backend +go run main.go +``` + +#### PostgreSQL (Environnement de Développement Docker) + +```bash +# Démarrer en utilisant docker-compose.dev.yml +make dev-api +``` + +### Structure du Projet + +``` +. +├── router/ # Routage HTTP +├── controller/ # Gestionnaires de requêtes +├── service/ # Logique métier +├── model/ # Modèles de données (GORM) +├── relay/ # Relais/proxy API AI +│ └── channel/ # Adaptateurs spécifiques aux fournisseurs (openai/, claude/, gemini/, etc.) +├── middleware/ # Middleware (auth, limitation de débit, CORS, etc.) +├── setting/ # Gestion de la configuration +├── common/ # Fonctions utilitaires +├── dto/ # Objets de transfert de données +├── constant/ # Définitions de constantes +├── i18n/ # Internationalisation backend (en/zh) +└── web/ # Projets frontend + ├── default/ # Frontend par défaut (React 19) + └── classic/ # Frontend classique (React 18) +``` + +### Directives de Développement + +Voir [CLAUDE.md](../../CLAUDE.md) pour les détails, points clés: + +1. **Opérations JSON**: Doit utiliser les fonctions wrapper dans `common/json.go` +2. **Compatibilité Base de Données**: Le code doit être compatible avec SQLite/MySQL/PostgreSQL +3. **Gestionnaire de Paquets**: Le frontend priorise Bun + +## Compiler la Version de Production + +```bash +# Compiler le frontend +make build-all-frontends + +# Compiler le backend +go build -o new-api main.go + +# Ou utiliser Docker +docker build -t new-api . +``` + +## Outils de Débogage + +### Réinitialiser l'Assistant de Configuration + +```bash +make reset-setup +``` + +Cette commande efface les paramètres et les comptes administrateur dans la base de données pour retester l'assistant d'initialisation. + +## Problèmes Courants + +### Erreur go:embed: no matching files found + +**Problème**: Erreur au démarrage du backend `pattern web/*/dist: no matching files found` + +**Cause**: `main.go` utilise `//go:embed` pour intégrer les fichiers frontend au moment de la compilation, si le répertoire `dist` n'existe pas, il y aura une erreur. + +**Solution**: +```bash +# D'abord compiler le frontend pour générer dist +cd web/default && bun install && bun run build && cd ../.. + + +# Démarrer le backend +go run main.go +``` + +### Conflit de Port + +- Port par défaut du backend: 3000 +- Serveur de développement frontend: 5173 +- Frontend classique: 5174 + +**Problème**: Le démarrage du frontend affiche `Port 3000 is occupied` + +**Cause**: Rsbuild essaie d'utiliser le port 3000 par défaut, mais il est occupé par le backend. + +**Solution**: `port: 5173` est déjà configuré dans `rsbuild.config.ts`, exécutez simplement `bun run dev`. + +### Migration de Base de Données + +GORM effectue automatiquement les migrations. Toutes les tables sont créées automatiquement lors de la première exécution. + +### Configuration du Proxy Frontend + +Le serveur de développement frontend est configuré avec un proxy, les requêtes API sont automatiquement transférées au backend `http://localhost:3000`. + +## Documentation Associée + +- [Conventions du Projet (CLAUDE.md)](../../CLAUDE.md) +- [Documentation Utilisateur](https://docs.newapi.pro/en/docs) +- [Documentation API](https://docs.newapi.pro/en/docs/api) + +## Guide de Contribution + +Les contributions sont les bienvenues! Avant de soumettre une PR, veuillez vous assurer: + +1. Le code passe les vérifications lint +2. Suit les conventions du projet (voir CLAUDE.md) +3. Les tests passent +4. Messages de commit clairs + +--- + +**Support Technique**: [support@quantumnous.com](mailto:support@quantumnous.com) diff --git a/docs/development/DEVELOPMENT.ja.md b/docs/development/DEVELOPMENT.ja.md new file mode 100644 index 000000000000..8d71e0935424 --- /dev/null +++ b/docs/development/DEVELOPMENT.ja.md @@ -0,0 +1,247 @@ +# 開発ガイド + ++ 简体中文 | + 繁體中文 | + English | + Français | + 日本語 +
+ +このドキュメントは、開発者向けに new-api プロジェクトをローカルで実行・開発する方法を説明します。 + +## 必要な環境 + +- **Go**: 1.22+ (プロジェクトは 1.25.1 を使用) +- **Bun**: フロントエンドパッケージマネージャー (npm/yarn より優先) +- **Database**: SQLite (デフォルト) / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 +- **Docker** (オプション): コンテナ化された開発環境用 + +## クイックスタート + +### 方法1: ローカル開発 (推奨) + +> **前提条件**: Go は `//go:embed` を使用してフロントエンドファイルを埋め込むため、初回起動前に一度フロントエンドをビルドする必要があります。そうしないとエラーが発生します。 + +#### 1. 初回セットアップ + +```bash +# フロントエンドをビルド (go:embed エラーを避けるため dist ディレクトリを生成) +cd web/default +bun install +bun run build +cd ../.. + +``` + +#### 2. バックエンドの起動 + +```bash +# Go の依存関係をインストール +go mod download + +# バックエンドサービスを起動 (SQLite を使用) +go run main.go +``` + +バックエンドはデフォルトで `http://localhost:3000` で実行され、データは `one-api.db` に保存されます + +#### 3. フロントエンドの起動 + +```bash +# フロントエンドディレクトリに移動 +cd web/default + +# 依存関係をインストール +bun install + +# 開発サーバーを起動 +bun run dev +``` + +フロントエンド開発サーバーは `http://localhost:5173` で実行され、バックエンドリクエストをポート 3000 に自動的にプロキシします。 + +### 方法2: Makefile の使用 + +```bash +# バックエンドとフロントエンドを同時に起動 (Docker + フロントエンド開発サーバー) +make dev + +# バックエンドのみ起動 (Docker Compose) +make dev-api + +# フロントエンドのみ起動 +make dev-web + +# クラシックフロントエンドを起動 +make dev-web-classic +``` + +## フロントエンド開発 + +### 利用可能なコマンド + +`web/default/` ディレクトリ内: + +```bash +bun run dev # 開発サーバーを起動 (http://localhost:5173) +bun run build # プロダクションビルド +bun run preview # プロダクションビルドをプレビュー +bun run typecheck # TypeScript 型チェック +bun run lint # ESLint コードチェック +bun run format # Prettier コードフォーマット +bun run format:check # コードフォーマットをチェック +bun run i18n:sync # 国際化翻訳を同期 +``` + +### 技術スタック + +- **React 19** + **TypeScript** +- **Rsbuild** - ビルドツール +- **Base UI** - コンポーネントライブラリ +- **Tailwind CSS** - スタイリング +- **TanStack Router** - ルーティング +- **TanStack Query** - データフェッチング +- **i18next** - 国際化 (en/zh/fr/ru/ja/vi をサポート) + +### 国際化開発 + +翻訳ファイルは `web/default/src/i18n/locales/{lang}.json` にあります。翻訳を追加または修正した後、以下を実行してください: + +```bash +bun run i18n:sync +``` + +## バックエンド開発 + +### データベース設定 + +#### SQLite (デフォルト) + +設定は不要で、`go run main.go` を実行するだけです。 + +#### MySQL + +```bash +# 環境変数を設定 +export SQL_DSN="root:password@tcp(localhost:3306)/newapi" + +# バックエンドを起動 +go run main.go +``` + +#### PostgreSQL (Docker 開発環境) + +```bash +# docker-compose.dev.yml を使用して起動 +make dev-api +``` + +### プロジェクト構成 + +``` +. +├── router/ # HTTP ルーティング +├── controller/ # リクエストハンドラ +├── service/ # ビジネスロジック +├── model/ # データモデル (GORM) +├── relay/ # AI API リレー/プロキシ +│ └── channel/ # プロバイダー固有のアダプター (openai/, claude/, gemini/, etc.) +├── middleware/ # ミドルウェア (認証、レート制限、CORS など) +├── setting/ # 設定管理 +├── common/ # ユーティリティ関数 +├── dto/ # データ転送オブジェクト +├── constant/ # 定数定義 +├── i18n/ # バックエンド国際化 (en/zh) +└── web/ # フロントエンドプロジェクト + ├── default/ # デフォルトフロントエンド (React 19) + └── classic/ # クラシックフロントエンド (React 18) +``` + +### 開発ガイドライン + +詳細は [CLAUDE.md](../../CLAUDE.md) を参照してください。重要なポイント: + +1. **JSON 操作**: `common/json.go` のラッパー関数を使用する必要があります +2. **データベース互換性**: コードは SQLite/MySQL/PostgreSQL と互換性がある必要があります +3. **パッケージマネージャー**: フロントエンドは Bun を優先します + +## プロダクションバージョンのビルド + +```bash +# フロントエンドをビルド +make build-all-frontends + +# バックエンドをビルド +go build -o new-api main.go + +# または Docker を使用 +docker build -t new-api . +``` + +## デバッグツール + +### セットアップウィザードのリセット + +```bash +make reset-setup +``` + +このコマンドは、データベース内の設定と管理者アカウントをクリアし、初期化ウィザードを再テストします。 + +## よくある問題 + +### go:embed エラー: no matching files found + +**問題**: バックエンド起動時のエラー `pattern web/*/dist: no matching files found` + +**原因**: `main.go` は `//go:embed` を使用してコンパイル時にフロントエンドファイルを埋め込みます。`dist` ディレクトリが存在しない場合、エラーが発生します。 + +**解決策**: +```bash +# まずフロントエンドをビルドして dist を生成 +cd web/default && bun install && bun run build && cd ../.. + + +# バックエンドを起動 +go run main.go +``` + +### ポートの競合 + +- バックエンドのデフォルトポート: 3000 +- フロントエンド開発サーバー: 5173 +- クラシックフロントエンド: 5174 + +**問題**: フロントエンド起動時に `Port 3000 is occupied` と表示される + +**原因**: Rsbuild はデフォルトでポート 3000 を使用しようとしますが、バックエンドによって占有されています。 + +**解決策**: `rsbuild.config.ts` で既に `port: 5173` が設定されているため、`bun run dev` を実行するだけです。 + +### データベースマイグレーション + +GORM は自動的にマイグレーションを実行します。初回実行時にすべてのテーブルが自動的に作成されます。 + +### フロントエンドプロキシ設定 + +フロントエンド開発サーバーはプロキシが設定されており、API リクエストは自動的にバックエンド `http://localhost:3000` に転送されます。 + +## 関連ドキュメント + +- [プロジェクト規約 (CLAUDE.md)](../../CLAUDE.md) +- [ユーザードキュメント](https://docs.newapi.pro/en/docs) +- [API ドキュメント](https://docs.newapi.pro/en/docs/api) + +## 貢献ガイド + +貢献を歓迎します! PR を送信する前に、以下を確認してください: + +1. コードが lint チェックに合格すること +2. プロジェクト規約に従うこと (CLAUDE.md 参照) +3. テストが合格すること +4. 明確なコミットメッセージ + +--- + +**技術サポート**: [support@quantumnous.com](mailto:support@quantumnous.com) diff --git a/docs/development/DEVELOPMENT.md b/docs/development/DEVELOPMENT.md new file mode 100644 index 000000000000..30b7789a2ca0 --- /dev/null +++ b/docs/development/DEVELOPMENT.md @@ -0,0 +1,247 @@ +# Development Guide + ++ 简体中文 | + 繁體中文 | + English | + Français | + 日本語 +
+ +This document is for developers to explain how to run and develop the new-api project locally. + +## Requirements + +- **Go**: 1.22+ (project uses 1.25.1) +- **Bun**: Frontend package manager (preferred over npm/yarn) +- **Database**: SQLite (default) / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 +- **Docker** (optional): For containerized development environment + +## Quick Start + +### Method 1: Local Development (Recommended) + +> **Prerequisites**: Since Go uses `//go:embed` to embed frontend files, you must build the frontend once before the first startup, otherwise an error will occur. + +#### 1. First-Time Setup + +```bash +# Build frontend (generate dist directory to avoid go:embed error) +cd web/default +bun install +bun run build +cd ../.. + +``` + +#### 2. Start Backend + +```bash +# Install Go dependencies +go mod download + +# Start backend service (using SQLite) +go run main.go +``` + +Backend runs on `http://localhost:3000` by default, data stored in `one-api.db` + +#### 3. Start Frontend + +```bash +# Enter frontend directory +cd web/default + +# Install dependencies +bun install + +# Start development server +bun run dev +``` + +Frontend development server runs on `http://localhost:5173` and automatically proxies backend requests to port 3000. + +### Method 2: Using Makefile + +```bash +# Start both backend and frontend (Docker + frontend dev server) +make dev + +# Start backend only (Docker Compose) +make dev-api + +# Start frontend only +make dev-web + +# Start classic frontend +make dev-web-classic +``` + +## Frontend Development + +### Available Commands + +In `web/default/` directory: + +```bash +bun run dev # Start development server (http://localhost:5173) +bun run build # Production build +bun run preview # Preview production build +bun run typecheck # TypeScript type checking +bun run lint # ESLint code checking +bun run format # Prettier code formatting +bun run format:check # Check code format +bun run i18n:sync # Sync internationalization translations +``` + +### Tech Stack + +- **React 19** + **TypeScript** +- **Rsbuild** - Build tool +- **Base UI** - Component library +- **Tailwind CSS** - Styling +- **TanStack Router** - Routing +- **TanStack Query** - Data fetching +- **i18next** - Internationalization (supports en/zh/fr/ru/ja/vi) + +### Internationalization Development + +Translation files are located in `web/default/src/i18n/locales/{lang}.json`. After adding or modifying translations, run: + +```bash +bun run i18n:sync +``` + +## Backend Development + +### Database Configuration + +#### SQLite (Default) + +No configuration needed, just run `go run main.go`. + +#### MySQL + +```bash +# Set environment variable +export SQL_DSN="root:password@tcp(localhost:3306)/newapi" + +# Start backend +go run main.go +``` + +#### PostgreSQL (Docker Development Environment) + +```bash +# Start using docker-compose.dev.yml +make dev-api +``` + +### Project Structure + +``` +. +├── router/ # HTTP routing +├── controller/ # Request handlers +├── service/ # Business logic +├── model/ # Data models (GORM) +├── relay/ # AI API relay/proxy +│ └── channel/ # Provider-specific adapters (openai/, claude/, gemini/, etc.) +├── middleware/ # Middleware (auth, rate limiting, CORS, etc.) +├── setting/ # Configuration management +├── common/ # Utility functions +├── dto/ # Data transfer objects +├── constant/ # Constant definitions +├── i18n/ # Backend internationalization (en/zh) +└── web/ # Frontend projects + ├── default/ # Default frontend (React 19) + └── classic/ # Classic frontend (React 18) +``` + +### Development Guidelines + +See [CLAUDE.md](../../CLAUDE.md) for details, key points: + +1. **JSON Operations**: Must use wrapper functions in `common/json.go` +2. **Database Compatibility**: Code must be compatible with SQLite/MySQL/PostgreSQL +3. **Package Manager**: Frontend prioritizes Bun + +## Build Production Version + +```bash +# Build frontend +make build-all-frontends + +# Build backend +go build -o new-api main.go + +# Or use Docker +docker build -t new-api . +``` + +## Debugging Tools + +### Reset Setup Wizard + +```bash +make reset-setup +``` + +This command clears settings and admin accounts in the database for retesting the initialization wizard. + +## Common Issues + +### go:embed Error: no matching files found + +**Problem**: Backend startup error `pattern web/*/dist: no matching files found` + +**Cause**: `main.go` uses `//go:embed` to embed frontend files at compile time, if `dist` directory doesn't exist it will error. + +**Solution**: +```bash +# First build frontend to generate dist +cd web/default && bun install && bun run build && cd ../.. + + +# Start backend +go run main.go +``` + +### Port Conflict + +- Backend default port: 3000 +- Frontend development server: 5173 +- Classic frontend: 5174 + +**Problem**: Frontend startup shows `Port 3000 is occupied` + +**Cause**: Rsbuild tries to use port 3000 by default, but it's occupied by backend. + +**Solution**: Already configured `port: 5173` in `rsbuild.config.ts`, just run `bun run dev`. + +### Database Migration + +GORM automatically performs migrations. All tables are created automatically on first run. + +### Frontend Proxy Configuration + +Frontend development server is configured with proxy, API requests are automatically forwarded to backend `http://localhost:3000`. + +## Related Documentation + +- [Project Conventions (CLAUDE.md)](../../CLAUDE.md) +- [User Documentation](https://docs.newapi.pro/en/docs) +- [API Documentation](https://docs.newapi.pro/en/docs/api) + +## Contribution Guide + +Contributions are welcome! Before submitting a PR, please ensure: + +1. Code passes lint checks +2. Follows project conventions (see CLAUDE.md) +3. Tests pass +4. Clear commit messages + +--- + +**Technical Support**: [support@quantumnous.com](mailto:support@quantumnous.com) diff --git a/docs/development/DEVELOPMENT.zh_CN.md b/docs/development/DEVELOPMENT.zh_CN.md new file mode 100644 index 000000000000..7842419e4512 --- /dev/null +++ b/docs/development/DEVELOPMENT.zh_CN.md @@ -0,0 +1,247 @@ +# 开发文档 / Development Guide + + + +本文档面向开发者，说明如何在本地运行和开发 new-api 项目。 + +## 环境要求 + +- **Go**: 1.22+ (项目使用 1.25.1) +- **Bun**: 前端包管理器（优先于 npm/yarn） +- **数据库**: SQLite（默认）/ MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 +- **Docker** (可选): 用于容器化开发环境 + +## 快速启动 + +### 方式一：本地开发（推荐） + +> **前置要求**：由于 Go 使用 `//go:embed` 嵌入前端文件，首次启动前必须先构建一次前端，否则会报错。 + +#### 1. 首次启动准备 + +```bash +# 构建前端（生成 dist 目录，避免 go:embed 报错） +cd web/default +bun install +bun run build +cd ../.. + +``` + +#### 2. 启动后端 + +```bash +# 安装 Go 依赖 +go mod download + +# 启动后端服务（使用 SQLite） +go run main.go +``` + +后端默认运行在 `http://localhost:3000`，数据存储在 `one-api.db` + +#### 3. 启动前端 + +```bash +# 进入前端目录 +cd web/default + +# 安装依赖 +bun install + +# 启动开发服务器 +bun run dev +``` + +前端开发服务器运行在 `http://localhost:5173`，会自动代理后端请求到 3000 端口。 + +### 方式二：使用 Makefile + +```bash +# 同时启动后端和前端（Docker + 前端开发服务器） +make dev + +# 仅启动后端（Docker Compose） +make dev-api + +# 仅启动前端 +make dev-web + +# 启动经典前端 +make dev-web-classic +``` + +## 前端开发 + +### 可用命令 + +在 `web/default/` 目录下： + +```bash +bun run dev # 启动开发服务器 (http://localhost:5173) +bun run build # 生产构建 +bun run preview # 预览生产构建 +bun run typecheck # TypeScript 类型检查 +bun run lint # ESLint 代码检查 +bun run format # Prettier 格式化代码 +bun run format:check # 检查代码格式 +bun run i18n:sync # 同步国际化翻译 +``` + +### 技术栈 + +- **React 19** + **TypeScript** +- **Rsbuild** - 构建工具 +- **Base UI** - 组件库 +- **Tailwind CSS** - 样式 +- **TanStack Router** - 路由 +- **TanStack Query** - 数据请求 +- **i18next** - 国际化（支持 en/zh/fr/ru/ja/vi） + +### 国际化开发 + +翻译文件位于 `web/default/src/i18n/locales/{lang}.json`。添加或修改翻译后，运行： + +```bash +bun run i18n:sync +``` + +## 后端开发 + +### 数据库配置 + +#### SQLite（默认） + +无需配置，直接运行 `go run main.go` 即可。 + +#### MySQL + +```bash +# 设置环境变量 +export SQL_DSN="root:password@tcp(localhost:3306)/newapi" + +# 启动后端 +go run main.go +``` + +#### PostgreSQL（Docker 开发环境） + +```bash +# 使用 docker-compose.dev.yml 启动 +make dev-api +``` + +### 项目结构 + +``` +. +├── router/ # HTTP 路由 +├── controller/ # 请求处理器 +├── service/ # 业务逻辑 +├── model/ # 数据模型（GORM） +├── relay/ # AI API 中继/代理 +│ └── channel/ # 各提供商适配器 (openai/, claude/, gemini/ 等) +├── middleware/ # 中间件（认证、限流、CORS 等） +├── setting/ # 配置管理 +├── common/ # 工具函数 +├── dto/ # 数据传输对象 +├── constant/ # 常量定义 +├── i18n/ # 后端国际化（en/zh） +└── web/ # 前端项目 + ├── default/ # 默认前端（React 19） + └── classic/ # 经典前端（React 18） +``` + +### 开发规范 + +详见 [CLAUDE.md](../../CLAUDE.md)，重点： + +1. **JSON 操作**：必须使用 `common/json.go` 中的封装函数 +2. **数据库兼容**：代码必须同时兼容 SQLite/MySQL/PostgreSQL +3. **包管理器**：前端优先使用 Bun + +## 构建生产版本 + +```bash +# 构建前端 +make build-all-frontends + +# 构建后端 +go build -o new-api main.go + +# 或使用 Docker +docker build -t new-api . +``` + +## 调试工具 + +### 重置设置向导 + +```bash +make reset-setup +``` + +此命令会清除数据库中的设置和管理员账户，用于重新测试初始化向导。 + +## 常见问题 + +### go:embed 报错：no matching files found + +**问题**：启动后端时报错 `pattern web/*/dist: no matching files found` + +**原因**：`main.go` 使用 `//go:embed` 在编译时嵌入前端文件，如果 `dist` 目录不存在会报错。 + +**解决**： +```bash +# 先构建前端生成 dist +cd web/default && bun install && bun run build && cd ../.. + + +# 启动后端 +go run main.go +``` + +### 端口冲突 + +- 后端默认端口：3000 +- 前端开发服务器：5173 +- 经典前端：5174 + +**问题**：前端启动时提示 `Port 3000 is occupied` + +**原因**：Rsbuild 默认尝试使用 3000 端口，但被后端占用。 + +**解决**：已在 `rsbuild.config.ts` 中配置 `port: 5173`，直接运行 `bun run dev` 即可。 + +### 数据库迁移 + +GORM 会自动执行迁移。首次运行时会自动创建所有表。 + +### 前端代理配置 + +前端开发服务器已配置代理，API 请求会自动转发到后端 `http://localhost:3000`。 + +## 相关文档 + +- [项目约定 (CLAUDE.md)](../../CLAUDE.md) +- [用户文档](https://docs.newapi.pro/zh/docs) +- [API 文档](https://docs.newapi.pro/zh/docs/api) + +## 贡献指南 + +欢迎贡献！提交 PR 前请确保： + +1. 代码通过 lint 检查 +2. 遵循项目约定（见 CLAUDE.md） +3. 测试通过 +4. 提交信息清晰 + +--- + +**技术支持**: [support@quantumnous.com](mailto:support@quantumnous.com) diff --git a/docs/development/DEVELOPMENT.zh_TW.md b/docs/development/DEVELOPMENT.zh_TW.md new file mode 100644 index 000000000000..513f5b1d1272 --- /dev/null +++ b/docs/development/DEVELOPMENT.zh_TW.md @@ -0,0 +1,247 @@ +# 開發指南 + + + +本文件面向開發者，說明如何在本地運行和開發 new-api 項目。 + +## 環境要求 + +- **Go**: 1.22+ (項目使用 1.25.1) +- **Bun**: 前端套件管理器 (優先使用，而非 npm/yarn) +- **Database**: SQLite (預設) / MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6 +- **Docker** (可選): 用於容器化開發環境 + +## 快速開始 + +### 方式一：本地開發 (推薦) + +> **前置條件**: 由於 Go 使用 `//go:embed` 嵌入前端檔案，首次啟動前必須先構建一次前端，否則會報錯。 + +#### 1. 首次設置 + +```bash +# 構建前端 (生成 dist 目錄以避免 go:embed 錯誤) +cd web/default +bun install +bun run build +cd ../.. + +``` + +#### 2. 啟動後端 + +```bash +# 安裝 Go 依賴 +go mod download + +# 啟動後端服務 (使用 SQLite) +go run main.go +``` + +後端預設運行在 `http://localhost:3000`，數據儲存在 `one-api.db` + +#### 3. 啟動前端 + +```bash +# 進入前端目錄 +cd web/default + +# 安裝依賴 +bun install + +# 啟動開發伺服器 +bun run dev +``` + +前端開發伺服器運行在 `http://localhost:5173`，會自動代理後端請求到 3000 埠。 + +### 方式二：使用 Makefile + +```bash +# 同時啟動後端和前端 (Docker + 前端開發伺服器) +make dev + +# 僅啟動後端 (Docker Compose) +make dev-api + +# 僅啟動前端 +make dev-web + +# 啟動經典版前端 +make dev-web-classic +``` + +## 前端開發 + +### 可用命令 + +在 `web/default/` 目錄下： + +```bash +bun run dev # 啟動開發伺服器 (http://localhost:5173) +bun run build # 生產環境構建 +bun run preview # 預覽生產構建 +bun run typecheck # TypeScript 類型檢查 +bun run lint # ESLint 代碼檢查 +bun run format # Prettier 代碼格式化 +bun run format:check # 檢查代碼格式 +bun run i18n:sync # 同步國際化翻譯 +``` + +### 技術棧 + +- **React 19** + **TypeScript** +- **Rsbuild** - 構建工具 +- **Base UI** - 組件庫 +- **Tailwind CSS** - 樣式 +- **TanStack Router** - 路由 +- **TanStack Query** - 數據獲取 +- **i18next** - 國際化 (支援 en/zh/fr/ru/ja/vi) + +### 國際化開發 + +翻譯檔案位於 `web/default/src/i18n/locales/{lang}.json`。新增或修改翻譯後，運行： + +```bash +bun run i18n:sync +``` + +## 後端開發 + +### 數據庫配置 + +#### SQLite (預設) + +無需配置，直接運行 `go run main.go`。 + +#### MySQL + +```bash +# 設置環境變數 +export SQL_DSN="root:password@tcp(localhost:3306)/newapi" + +# 啟動後端 +go run main.go +``` + +#### PostgreSQL (Docker 開發環境) + +```bash +# 使用 docker-compose.dev.yml 啟動 +make dev-api +``` + +### 項目結構 + +``` +. +├── router/ # HTTP 路由 +├── controller/ # 請求處理器 +├── service/ # 業務邏輯 +├── model/ # 數據模型 (GORM) +├── relay/ # AI API 中繼/代理 +│ └── channel/ # 供應商特定適配器 (openai/, claude/, gemini/, etc.) +├── middleware/ # 中間件 (認證、限流、CORS 等) +├── setting/ # 配置管理 +├── common/ # 工具函數 +├── dto/ # 數據傳輸物件 +├── constant/ # 常量定義 +├── i18n/ # 後端國際化 (en/zh) +└── web/ # 前端項目 + ├── default/ # 預設前端 (React 19) + └── classic/ # 經典版前端 (React 18) +``` + +### 開發規範 + +詳見 [CLAUDE.md](../../CLAUDE.md)，重點： + +1. **JSON 操作**: 必須使用 `common/json.go` 中的包裝函數 +2. **數據庫兼容性**: 代碼必須兼容 SQLite/MySQL/PostgreSQL +3. **套件管理器**: 前端優先使用 Bun + +## 構建生產版本 + +```bash +# 構建前端 +make build-all-frontends + +# 構建後端 +go build -o new-api main.go + +# 或使用 Docker +docker build -t new-api . +``` + +## 調試工具 + +### 重置設置嚮導 + +```bash +make reset-setup +``` + +此命令會清除數據庫中的設置和管理員帳號，用於重新測試初始化嚮導。 + +## 常見問題 + +### go:embed 錯誤: no matching files found + +**問題**: 後端啟動報錯 `pattern web/*/dist: no matching files found` + +**原因**: `main.go` 使用 `//go:embed` 在編譯時嵌入前端檔案，如果 `dist` 目錄不存在會報錯。 + +**解決方案**: +```bash +# 先構建前端生成 dist +cd web/default && bun install && bun run build && cd ../.. + + +# 啟動後端 +go run main.go +``` + +### 埠衝突 + +- 後端預設埠: 3000 +- 前端開發伺服器: 5173 +- 經典版前端: 5174 + +**問題**: 前端啟動顯示 `Port 3000 is occupied` + +**原因**: Rsbuild 預設嘗試使用 3000 埠，但被後端佔用。 + +**解決方案**: 已在 `rsbuild.config.ts` 中配置 `port: 5173`，直接運行 `bun run dev` 即可。 + +### 數據庫遷移 + +GORM 會自動執行遷移。首次運行時所有表會自動創建。 + +### 前端代理配置 + +前端開發伺服器已配置代理，API 請求會自動轉發到後端 `http://localhost:3000`。 + +## 相關文件 + +- [項目規範 (CLAUDE.md)](../../CLAUDE.md) +- [用戶文件](https://docs.newapi.pro/en/docs) +- [API 文件](https://docs.newapi.pro/en/docs/api) + +## 貢獻指南 + +歡迎貢獻！提交 PR 前請確保： + +1. 代碼通過 lint 檢查 +2. 遵循項目規範 (見 CLAUDE.md) +3. 測試通過 +4. 清晰的 commit 訊息 + +--- + +**技術支援**: [support@quantumnous.com](mailto:support@quantumnous.com)