vite-press init

docs/en/reference/api.md

@@ -0,0 +1,44 @@
+# API Conventions
+
+Management API and Agent API both use JSON.
+
+## Response Shape
+
+Success and failure responses should include a clear `message`:
+
+```json
+{
+  "success": true,
+  "message": "",
+  "data": {}
+}
+```
+
+## Paths
+
+| Type | Convention |
+| --- | --- |
+| Management API | Authenticated by management Session |
+| Agent API | Fixed under `/api/agent/*` |
+| Read-only endpoints | `GET` |
+| Mutating endpoints | `POST` |
+
+## Authentication
+
+Management endpoints 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:
+
+```http
+X-Agent-Token: <token>
+```
+
+Do not log full tokens.
+
+## Swagger
+
+After logging in:
+
+```text
+/swagger/index.html
+```

docs/en/reference/cli.md

@@ -0,0 +1,64 @@
+# Commands and Scripts
+
+## Server
+
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-random-string'
+export SQLITE_PATH='./openflare.db'
+export LOG_LEVEL='info'
+go run .
+```
+
+```bash
+go run . --port 3000 --log-dir ./logs
+```
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+## Frontend
+
+```bash
+cd openflare_server/web
+pnpm install
+pnpm dev
+```
+
+```bash
+cd openflare_server/web
+pnpm build
+```
+
+## Agent
+
+```bash
+cd openflare_agent
+go run ./cmd/agent -config /path/to/agent.json
+```
+
+```bash
+cd openflare_agent
+go build -o openflare-agent ./cmd/agent
+```
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+## Install Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+## Uninstall Agent
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
+```

docs/en/reference/configuration.md

@@ -0,0 +1,74 @@
+# Configuration
+
+## Server CLI Flags
+
+| Flag | Purpose | Default |
+| --- | --- | --- |
+| `--port` | Server listen port | `3000` |
+| `--log-dir` | Log directory | empty |
+| `--version` | Print version and exit | `false` |
+| `--help` | Print help and exit | `false` |
+
+## Server Environment Variables
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `PORT` | Server listen port | `3000` |
+| `GIN_MODE` | Gin mode | release unless `debug` |
+| `LOG_LEVEL` | Log level | `info` |
+| `SESSION_SECRET` | Session signing secret | random on startup |
+| `SQLITE_PATH` | SQLite database path | `openflare.db` |
+| `DSN` | PostgreSQL DSN, preferred over SQLite | empty |
+| `SQL_DSN` | Legacy PostgreSQL DSN, lower priority than `DSN` | empty |
+| `REDIS_CONN_STRING` | Redis connection string | empty |
+| `UPLOAD_PATH` | Upload directory | `upload` |
+| `AGENT_TOKEN` | Legacy global Agent token | empty |
+
+When `DSN` and `SQL_DSN` both exist, `DSN` wins. PostgreSQL is preferred when configured. If PostgreSQL is empty and a local SQLite file exists, Server migrates SQLite data at startup.
+
+## Frontend Build Variables
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `NEXT_PUBLIC_API_BASE_URL` | Frontend API base path | `/api` |
+| `NEXT_PUBLIC_APP_VERSION` | Displayed frontend version | `dev` |
+| `NEXT_DEV_BACKEND_URL` | Local dev backend proxy target | `http://127.0.0.1:3000` |
+
+## Runtime Options
+
+The settings page maintains these hot-updatable options:
+
+| Option | Purpose | Default |
+| --- | --- | --- |
+| `AgentHeartbeatInterval` | Agent heartbeat interval in milliseconds | `10000` |
+| `NodeOfflineThreshold` | Node offline threshold in milliseconds | `120000` |
+| `AgentUpdateRepo` | Agent update repository | `Rain-kl/OpenFlare` |
+| `GeoIPProvider` | Node/IP region provider | `ipinfo` |
+| `RegisterEnabled` | Allow new user registration | `false` |
+| `PasswordRegisterEnabled` | Allow password registration | `true` |
+| `DatabaseAutoCleanupEnabled` | Enable daily observability cleanup | `false` |
+| `DatabaseAutoCleanupRetentionDays` | Retention days | `30` |
+
+OpenResty performance and cache options are also stored in the Option table, including `OpenRestyWorkerProcesses`, `OpenRestyWorkerConnections`, `OpenRestyProxyConnectTimeout`, `OpenRestyProxyReadTimeout`, `OpenRestyCacheEnabled`, `OpenRestyCachePath`, and `OpenRestyCacheMaxSize`.
+
+## Agent Configuration
+
+Agent supports the `-config` CLI flag, an `agent.json` file, and the `LOG_LEVEL` environment variable.
+
+| Field | Purpose | Required | Default / behavior |
+| --- | --- | --- | --- |
+| `server_url` | Control plane URL | yes | none |
+| `agent_token` | Node-specific auth token | one of `agent_token` / `discovery_token` | empty |
+| `discovery_token` | Global token for first registration | one of `agent_token` / `discovery_token` | empty |
+| `node_name` | Node name | no | host name |
+| `node_ip` | Node IP | no | auto-detected |
+| `openresty_path` | Local OpenResty path | no | empty; Docker mode |
+| `openresty_container_name` | Docker container name | no | `openflare-openresty` |
+| `openresty_docker_image` | Docker image | no | `openresty/openresty:alpine` |
+| `openresty_observability_port` | Local observability port | no | `18081` |
+| `docker_binary` | Docker binary name or path | no | `docker` |
+| `data_dir` | Agent data directory | no | `data` under config directory |
+| `heartbeat_interval` | Heartbeat interval | no | `10000` ms |
+| `request_timeout` | HTTP timeout | no | `10000` ms |
+
+`heartbeat_interval` and `request_timeout` accept milliseconds or Go duration strings.

docs/en/reference/index.md

@@ -0,0 +1,10 @@
+# Reference
+
+This section collects stable runtime, API, and repository information for deployment, integration, 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 |
+| [Repository Layout](./repository.md) | Responsibilities of `openflare_server`, `openflare_agent`, `openflare_server/web`, and `docs` |

docs/en/reference/repository.md

@@ -0,0 +1,32 @@
+# Repository Layout
+
+| 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 |
+
+## Server Layers
+
+| Directory | Responsibility |
+| --- | --- |
+| `controller/` | Parse input, call service, return response |
+| `service/` | Business logic, validation, transactions, rendering |
+| `model/` | Models, database versioning, migrations |
+| `router/` | Route registration |
+| `middleware/` | Auth, authorization, rate limiting, cross-cutting logic |
+| `common/` | Configuration, global state, initialization |
+| `utils/` | Pure helpers |
+
+## Frontend Layers
+
+| 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 |