tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-08 16:46:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

[新增] 同步更新英文版文档

Browse Source
This commit is contained in:
ryan
2026-05-28 23:00:48 +08:00
parent 95d58eb724
commit b0117b7c84
11 changed files with 870 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/guide/first-site.md
+81 -13
View File
@@ -1,32 +1,100 @@
# Publish First Site
# Publishing Your First Configuration
OpenFlare publishes complete configuration versions. After editing a site, publish and activate a new version before Agents apply it.
You will learn: How to create your first site configuration, bind origins and certificates, publish a configuration version, and confirm that the Agent has applied it.
OpenFlare's release link is centered on complete configuration versions. After modifying site configurations on the management console, you need to publish and activate the new version before the Agent pulls and applies it in subsequent heartbeats.
## Pre-release Check
Confirm that the following conditions are met:
| Project | Expectation |
| --- | --- |
| Server | Can log into the management console |
| Agent | At least one node is online |
| Origin | The Agent node can access the origin address |
| Domain | The domain has been resolved to the OpenResty node, or you are ready to verify via local hosts / curl Host header |
| HTTPS | If HTTPS is required, the certificate has been uploaded or hosted |
## Create Site Configuration
Required fields:
When adding a site configuration on the management console, you need at least:
| Field | Description |
| --- | --- |
| Site name | Business-unique identifier; defaults to the primary domain when omitted |
| Domains | At least one domain; the first one is the primary domain |
| Origin URL | Valid `http://` or `https://` upstream URL |
| Enabled | Only enabled sites are rendered into releases |
| Site Name | Unique business identifier; defaults to the primary domain when omitted |
| Domains | At least one domain; the first item is treated as the primary domain |
| Origin URL | Valid `http://` or `https://` upstream address |
| Enabled | Only enabled site configurations participate in release rendering |
A domain can belong to only one site.
Example:
| Field | Example |
| --- | --- |
| Site Name | `app` |
| Domains | `app.example.com` |
| Origin URL | `http://10.0.0.20:8080` |
A domain can belong to only one site configuration. Site-level rate limits, reverse proxies, and cache configurations are shared by site.
## Bind Certificates
HTTPS certificates are bound per domain. Domains without certificates are not automatically rendered into `443 ssl` server blocks.
HTTPS certificates are bound per domain. Domains not bound to certificates will not be automatically placed in `443 ssl` server blocks.
If a site contains multiple domains, the publishing rendering will generate HTTPS configurations grouped by certificate and ensure all domains still belong to the same site snapshot.
## Publish and Activate
Standard link:
```text
Edit rules -> Preview / diff -> Publish -> Create full version -> Activate -> Agent pulls -> Agent applies -> Agent reports
Modify rules -> Preview / View diff -> Publish -> Generate complete configuration version -> Activate version -> Agent pulls -> Local application -> Report result
```
Server reads enabled sites, OpenResty template, performance options, and cache options, renders a full configuration, computes `checksum`, writes `config_versions`, then switches the active version.
When publishing, the Server reads all enabled site configurations, OpenResty main configuration templates, performance parameters, and cache parameters, renders the complete OpenResty configuration, calculates the `checksum`, writes to `config_versions`, and then switches the activated version.
## Verify
## Verify Results
Check that the node is online, the node version matches the active version, the latest apply log succeeded, and the version page marks the new version as active.
After publishing, confirm on the management console:
| Location | Expected Result |
| --- | --- |
| Node List | Node is online |
| Node Details | The current version is consistent with the activated version |
| Apply Logs | The most recent application succeeded |
| Version Page | The new version is in the activated state |
Confirm the Agent logs on the node:
```bash
journalctl -u openflare-agent -n 100 --no-pager
```
Access using the domain:
```bash
curl -I http://app.example.com
```
If the domain has not been officially resolved yet, you can temporarily specify the Host header to access the node IP:
```bash
curl -I -H 'Host: app.example.com' http://NODE_IP
```
HTTPS verification:
```bash
curl -I https://app.example.com
```
## Rollback
If the target version application fails and rolls back, the Agent will block repeated applications of the same `version + checksum` locally until the activated version or checksum on the control plane changes.
To roll back to an older version:
1. Open the configuration version page.
2. Find the previous confirmed working historical version.
3. Reactivate that version.
4. View the node application records to confirm that the Agent applied it successfully.
docs/en/guide/server.md
+71 -17
View File
@@ -1,18 +1,23 @@
# Run Server
# Starting the Server
OpenFlare Server is the Gin + GORM control plane. It owns the web console, management API, Agent API, configuration rendering, release publishing, and state storage.
You will learn: How to build the management console frontend from source, start OpenFlare Server, select SQLite or PostgreSQL, and access Swagger.
## Requirements
OpenFlare Server is a Gin + GORM monolithic control plane, responsible for the management console UI, management APIs, Agent APIs, configuration rendering, version releases, data storage, and aggregated queries.
| Item | Requirement |
| --- |-------------------------------------------------------|
| Go | `1.25+` |
| Node.js | `18+` |
| Database | Writable SQLite path or reachable PostgreSQL instance |
## Prerequisites
Set `SESSION_SECRET` explicitly in production and prefer PostgreSQL.
| Project | Requirement |
| --- | --- |
| Go | `1.25+` |
| Node.js | `18+` |
| pnpm | Recommended to use the pnpm declared by the project via `corepack enable` |
| Database | SQLite file directory is writable, or an accessible PostgreSQL instance |
## Build Frontend
In production environments, it is recommended to explicitly configure `SESSION_SECRET` and prioritize PostgreSQL.
## Build the Management Console Frontend
The Go Server hosts the static artifacts in `openflare_server/web/build`. Before starting from source, build the frontend first:
```bash
cd openflare_server/web
@@ -21,32 +26,81 @@ pnpm install
pnpm build
```
## Run from Source
Common frontend checks:
```bash
pnpm lint
pnpm typecheck
pnpm test
```
## Start with SQLite
```bash
cd openflare_server
export SESSION_SECRET='replace-with-random-string'
export SESSION_SECRET='replace-with-a-long-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
# Optional PostgreSQL:
# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
go run .
```
The default port is `3000`.
Listens on port `3000` by default. Access:
```text
http://localhost:3000
```
## Start with PostgreSQL
```bash
cd openflare_server
export SESSION_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
export LOG_LEVEL='info'
go run .
```
`DSN` takes precedence over SQLite once set. When `DSN` and the legacy-named `SQL_DSN` both exist, `DSN` takes precedence.
If the target PostgreSQL database is empty and the local `SQLITE_PATH` file exists, the Server will attempt to migrate SQLite data to PostgreSQL during the startup phase and output the migration progress in the logs.
## Command Line Parameters
```bash
go run . --port 3000 --log-dir ./logs
```
| Parameter | Action | Default Value |
| --- | --- | --- |
| `--port` | Specify the Server listening port | `3000` |
| `--log-dir` | Specify the log directory | Empty (outputs to standard output) |
| `--version` | Output the version and exit | `false` |
| `--help` | Output the help information and exit | `false` |
## First Login
Default account:
| Username | Password |
| --- | --- |
| `root` | `123456` |
Please change the default password immediately after logging in for the first time.
## Swagger
After logging in, open:
Access after logging into the management console:
```text
http://localhost:3000/swagger/index.html
```
Regenerate Swagger files locally:
Regenerate Swagger locally:
```bash
go install github.com/swaggo/swag/cmd/swag@v1.16.4
cd openflare_server
swag init -g main.go -o docs
```
The generated Swagger files are located in `openflare_server/docs`.
docs/en/guide/upgrade.md
+48 -10
View File
@@ -1,16 +1,29 @@
# Upgrade and Maintenance
You will learn: How to upgrade the Server and Agent, how to clean up observability data, and which verification commands to execute before and after maintenance.
Before upgrading, it is recommended to confirm the current activated version, the latest Agent application result, and the database backup policy. Do not upgrade in production environments while configuration publishing, large-scale Agent reconnection, or database migrations are in progress.
## Server Upgrade
Root users can check and upgrade stable Server releases from the console header. Manual binary upload is also supported.
Root users can check and upgrade the Server stable version from the top bar of the management console. Upgrades can also be confirmed and executed by uploading the Server binary.
Preview releases require manual selection. Stable releases are recommended for production.
To try a preview version, you can manually check the corresponding release. It is recommended to prioritize the stable version in production environments.
After upgrading, confirm:
```bash
docker compose ps
docker compose logs -n 100 openflare
```
If it is a source deployment, confirm that there are no database migration or startup errors in the logs after restarting the Server.
## Agent Upgrade
Agents follow stable releases by default. Preview upgrades must be triggered manually.
Node Agents follow stable versions by default for automatic updates. Preview upgrades must be triggered manually.
The install script can be re-run for reinstall or upgrade:
The installation script can be executed repeatedly to reinstall or upgrade the Agent:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -18,30 +31,55 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
--agent-token YOUR_AGENT_TOKEN
```
Note: Currently, the installation script will delete the entire installation directory during reinstallation, including the old `agent.json`, local state, cache data, and downloaded binaries. Please confirm that you still have a usable Token on hand before executing.
After upgrading, confirm:
```bash
systemctl status openflare-agent
journalctl -u openflare-agent -n 100 --no-pager
```
## Data Maintenance
The settings page controls observability cleanup:
The settings page of the management console can maintain the observability data automatic cleanup policy:
| Option | Description |
| Configuration Item | Description |
| --- | --- |
| `DatabaseAutoCleanupEnabled` | Enable daily cleanup |
| `DatabaseAutoCleanupRetentionDays` | Retention days, minimum 1 |
| `DatabaseAutoCleanupEnabled` | Whether to enable daily automatic cleanup |
| `DatabaseAutoCleanupRetentionDays` | Automatic cleanup retention days, at least 1 day |
When enabled, Server cleans access logs, metric snapshots, and request reports at 03:00 every day.
Once enabled, the Server will clean up access logs, metric snapshots, and request reports at 3 AM every day.
## Validation Commands
## Common Verification Commands
Server:
```bash
cd openflare_server
GOCACHE=/tmp/openflare-go-cache go test ./...
```
Agent:
```bash
cd openflare_agent
GOCACHE=/tmp/openflare-go-cache go test ./...
```
Frontend:
```bash
cd openflare_server/web
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```
Docs:
```bash
cd docs
pnpm build
```