mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-08 00:26:37 +08:00
[新增] 同步更新英文版文档
This commit is contained in:
ryan
+15
-11
@@ -1,10 +1,12 @@
|
||||
# API Conventions
|
||||
|
||||
Management API and Agent API both use JSON.
|
||||
You will learn: The response structure, path conventions, authentication methods, and Swagger entry point for OpenFlare management and Agent APIs.
|
||||
|
||||
## Response Shape
|
||||
Both the OpenFlare management APIs and Agent APIs use JSON.
|
||||
|
||||
Success and failure responses should include a clear `message`:
|
||||
## Response Structure
|
||||
|
||||
Both success and failure should return a clear `message`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -14,31 +16,33 @@ Success and failure responses should include a clear `message`:
|
||||
}
|
||||
```
|
||||
|
||||
## Paths
|
||||
## Path Conventions
|
||||
|
||||
| Type | Convention |
|
||||
| --- | --- |
|
||||
| Management API | Authenticated by management Session |
|
||||
| Management API | Authenticated by management console Session |
|
||||
| Agent API | Fixed under `/api/agent/*` |
|
||||
| Read-only endpoints | `GET` |
|
||||
| Mutating endpoints | `POST` |
|
||||
| Read-only API | Use `GET` |
|
||||
| Mutation-type API | Use `POST` |
|
||||
|
||||
## Authentication
|
||||
|
||||
Management endpoints reuse the existing login, role, and Session system.
|
||||
The management console continues to reuse the existing login, role, and Session system.
|
||||
|
||||
Agent requests use the node-specific `agent_token`. First-time registration can use a global `discovery_token`. The header is:
|
||||
Official Agent requests uniformly use the node-exclusive `agent_token`; the first access can use the global `discovery_token`. The Agent request header is fixed as:
|
||||
|
||||
```http
|
||||
X-Agent-Token: <token>
|
||||
```
|
||||
|
||||
Do not log full tokens.
|
||||
Full Tokens must not be printed in the logs.
|
||||
|
||||
## Swagger
|
||||
|
||||
After logging in:
|
||||
Accessible after logging into the management console:
|
||||
|
||||
```text
|
||||
/swagger/index.html
|
||||
```
|
||||
|
||||
The Swagger files are located in `openflare_server/docs`, generated by `swag init`.
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
# Commands and Scripts
|
||||
|
||||
You will learn: Common commands for starting, building, testing, installing, and uninstalling the OpenFlare Server, management console frontend, Agent, Swagger, and documentation site.
|
||||
|
||||
## Server
|
||||
|
||||
Start from source:
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
export SESSION_SECRET='replace-with-random-string'
|
||||
@@ -10,10 +14,14 @@ export LOG_LEVEL='info'
|
||||
go run .
|
||||
```
|
||||
|
||||
Specify listening port and log directory:
|
||||
|
||||
```bash
|
||||
go run . --port 3000 --log-dir ./logs
|
||||
```
|
||||
|
||||
Test:
|
||||
|
||||
```bash
|
||||
cd openflare_server
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
@@ -21,29 +29,48 @@ GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
|
||||
## Frontend
|
||||
|
||||
Development:
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Build static artifacts:
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
pnpm build
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
```bash
|
||||
cd openflare_server/web
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## Agent
|
||||
|
||||
Run from source:
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
go run ./cmd/agent -config /path/to/agent.json
|
||||
```
|
||||
|
||||
Compile:
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
go build -o openflare-agent ./cmd/agent
|
||||
```
|
||||
|
||||
Test:
|
||||
|
||||
```bash
|
||||
cd openflare_agent
|
||||
GOCACHE=/tmp/openflare-go-cache go test ./...
|
||||
@@ -62,3 +89,29 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
## Swagger
|
||||
|
||||
Regenerate Swagger documentation:
|
||||
|
||||
```bash
|
||||
go install github.com/swaggo/swag/cmd/swag@v1.16.4
|
||||
cd openflare_server
|
||||
swag init -g main.go -o docs
|
||||
```
|
||||
|
||||
## Docs
|
||||
|
||||
Local preview:
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
pnpm build
|
||||
```
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# Reference
|
||||
|
||||
This section collects stable runtime, API, and repository information for deployment, integration, and troubleshooting.
|
||||
You will learn: What information belongs to stable reference materials, and where to look up configurations, commands, APIs, and the repository structure.
|
||||
|
||||
This section collects stable information at the runtime, interface, and repository levels, suitable for quick lookups during deployment, joint debugging, and troubleshooting.
|
||||
|
||||
| Page | Content |
|
||||
| --- | --- |
|
||||
| [Configuration](./configuration.md) | Server environment variables, CLI flags, runtime options, and Agent config fields |
|
||||
| [Commands and Scripts](./cli.md) | Startup, build, test, install, and uninstall commands |
|
||||
| [API Conventions](./api.md) | Management API and Agent API response, auth, and path conventions |
|
||||
| [Configuration Items](./configuration.md) | Server environment variables, command line parameters, runtime Options, and Agent configuration fields |
|
||||
| [Commands and Scripts](./cli.md) | Common startup, build, test, install, and uninstall commands |
|
||||
| [API Conventions](./api.md) | Response structure, authentication, and path conventions of management and Agent APIs |
|
||||
| [Repository Layout](./repository.md) | Responsibilities of `openflare_server`, `openflare_agent`, `openflare_server/web`, and `docs` |
|
||||
|
||||
@@ -1,32 +1,47 @@
|
||||
# Repository Layout
|
||||
|
||||
You will learn: What the Server, Agent, frontend, scripts, and documentation directories in the OpenFlare repository are responsible for, and which layer to place your logic when contributing code.
|
||||
|
||||
| Path | Responsibility |
|
||||
| --- | --- |
|
||||
| `openflare_server` | Gin + GORM + SQLite/PostgreSQL control plane |
|
||||
| `openflare_server/web` | Next.js 15 App Router admin frontend, statically exported and served by Go Server |
|
||||
| `openflare_agent` | Go Agent running on nodes |
|
||||
| `scripts` | Agent install, uninstall, and helper scripts |
|
||||
| `docs` | VitePress docs site, design baseline, development rules, deployment and configuration docs |
|
||||
| `openflare_server` | Gin + GORM + SQLite/PostgreSQL monolithic control plane |
|
||||
| `openflare_server/web` | Next.js 15 App Router management console frontend, statically exported and hosted by the Go Server |
|
||||
| `openflare_agent` | Go monolithic Agent, running on the node side |
|
||||
| `scripts` | Helper scripts such as Agent installation, uninstallation, etc. |
|
||||
| `docs` | VitePress documentation site, design baseline, development constraints, deployment, and configuration documents |
|
||||
|
||||
## Server Layers
|
||||
## Server Layering
|
||||
|
||||
| Directory | Responsibility |
|
||||
| --- | --- |
|
||||
| `controller/` | Parse input, call service, return response |
|
||||
| `service/` | Business logic, validation, transactions, rendering |
|
||||
| `model/` | Models, database versioning, migrations |
|
||||
| `controller/` | Parameter parsing, calling services, returning responses |
|
||||
| `service/` | Business logic, verification, transaction orchestration, configuration rendering |
|
||||
| `model/` | Model definition, database version, and migration |
|
||||
| `router/` | Route registration |
|
||||
| `middleware/` | Auth, authorization, rate limiting, cross-cutting logic |
|
||||
| `common/` | Configuration, global state, initialization |
|
||||
| `utils/` | Pure helpers |
|
||||
| `middleware/` | Auth, authorization, rate limiting, and other cross-cutting logic |
|
||||
| `common/` | Configuration, global state, and initialization entry points |
|
||||
| `utils/` | Pure utility functions and general helpers |
|
||||
|
||||
## Frontend Layers
|
||||
## Agent Modules
|
||||
|
||||
| Module | Responsibility |
|
||||
| --- | --- |
|
||||
| `config` | Configuration reading and default values |
|
||||
| `heartbeat` | Heartbeat and version summary judgment |
|
||||
| `sync` | Configuration pulling and application orchestration |
|
||||
| `nginx` / `openresty` | OpenResty file writing, verification, reload, startup, and rollback |
|
||||
| `state` | Local state and observability supplementary reporting buffer |
|
||||
| `httpclient` | Server communication |
|
||||
| `protocol` | Agent API protocol types |
|
||||
| `internal/updater` | Agent self-updating |
|
||||
|
||||
## Frontend Layering
|
||||
|
||||
| Directory | Responsibility |
|
||||
| --- | --- |
|
||||
| `app/` | Routes, layouts, page composition |
|
||||
| `features/` | Business-domain modules |
|
||||
| `components/` | Cross-feature reusable components |
|
||||
| `lib/` | API client, env, utilities, constants |
|
||||
| `store/` | Small cross-page UI state |
|
||||
| `types/` | Shared types |
|
||||
| `app/` | Routes, layouts, page assembly |
|
||||
| `features/` | Organize modules by business domains |
|
||||
| `components/` | Reuse components across features |
|
||||
| `lib/` | Request client, environment variables, utility functions, constants |
|
||||
| `store/` | A small amount of cross-page UI state |
|
||||
| `types/` | Shared type definitions |
|
||||
|
||||
Reference in New Issue
Block a user