mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-09 09:06:36 +08:00
feat: 更新文档，添加环境变量和配置项说明，优化部署步骤，修改版本号格式
This commit is contained in:
ryan
+102
-58
@@ -2,15 +2,11 @@
|
||||
<a href="./README.md">中文</a> | <strong>English</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Rain-kl/ATSFlare"><img src="https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/atsf_server/web/public/logo.png" width="150" height="150" alt="ATSFlare logo"></a>
|
||||
</p>
|
||||
|
||||
<div align="center">
|
||||
|
||||
# ATSFlare
|
||||
|
||||
_✨ Internal Nginx control plane for reverse proxy management ✨_
|
||||
_✨ control plane for reverse proxy management ✨_
|
||||
|
||||
</div>
|
||||
|
||||
@@ -29,65 +25,113 @@ _✨ Internal Nginx control plane for reverse proxy management ✨_
|
||||
</a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Rain-kl/ATSFlare/releases">Download</a>
|
||||
·
|
||||
<a href="https://github.com/Rain-kl/ATSFlare/blob/main/README.en.md#deployment">Tutorial</a>
|
||||
·
|
||||
<a href="https://github.com/Rain-kl/ATSFlare/issues">Feedback</a>
|
||||
</p>
|
||||
## Repository layout
|
||||
|
||||
## Features
|
||||
+ [x] Built-in user management.
|
||||
+ [x] Built-in file management.
|
||||
+ [x] [GitHub OAuth](https://github.com/settings/applications/new).
|
||||
+ [x] WeChat official account authorization (need [wechat-server](https://github.com/songquanpeng/wechat-server)).
|
||||
+ [x] Email verification & password reset.
|
||||
+ [x] Request rate limiting.
|
||||
+ [x] Static files caching.
|
||||
+ [x] Mobile friendly UI.
|
||||
+ [x] Token based authorization.
|
||||
+ [x] Use GitHub Actions to build releases & Docker images.
|
||||
+ [x] Cloudflare Turnstile user validation.
|
||||
- `atsf_server`: Gin + GORM + SQLite control plane, including admin API, Agent API and Web UI
|
||||
- `atsf_agent`: single-binary Go Agent for registration, heartbeat, config sync and Nginx reload
|
||||
- `docs`: design, development guidelines, implementation plan and deployment docs
|
||||
|
||||
## Deployment
|
||||
### Manual deployment
|
||||
1. Download built binary from [GitHub Releases](https://github.com/Rain-kl/ATSFlare/releases/latest) or build from source:
|
||||
```shell
|
||||
git clone https://github.com/Rain-kl/ATSFlare.git
|
||||
go mod download
|
||||
go build -ldflags "-s -w" -o atsflare
|
||||
````
|
||||
2. Run it:
|
||||
```shell
|
||||
chmod u+x atsflare
|
||||
./atsflare --port 3000 --log-dir ./logs
|
||||
```
|
||||
3. Visit [http://localhost:3000/](http://localhost:3000/) and login. The username for the initial account is `root` and the password is `123456`.
|
||||
## Quick start
|
||||
|
||||
### Deploy with Docker
|
||||
Execute: `docker run -d --restart always -p 3000:3000 -v /home/ubuntu/data/atsflare:/data -v /etc/ssl/certs:/etc/ssl/certs:ro ghcr.io/rain-kl/atsflare`
|
||||
### 1. Start the Server
|
||||
|
||||
Data will be saved in `/home/ubuntu/data/atsflare`.
|
||||
The fastest way is to run the published GHCR image with Docker Compose:
|
||||
|
||||
## Configurations
|
||||
The system works out of the box.
|
||||
```yaml
|
||||
services:
|
||||
atsflare:
|
||||
image: ghcr.io/rain-kl/atsflare:latest
|
||||
container_name: atsflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
SESSION_SECRET: replace-with-random-string
|
||||
SQLITE_PATH: /data/atsflare.db
|
||||
GIN_MODE: release
|
||||
volumes:
|
||||
- atsflare-data:/data
|
||||
|
||||
You can configure the system by set environment variables or specify command line arguments.
|
||||
volumes:
|
||||
atsflare-data:
|
||||
```
|
||||
|
||||
After the system starts, use `root` user to log in to the system and do further configuration.
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
1. `REDIS_CONN_STRING`: when set, Redis will be used as the storage for request rate limitation instead of memory storage.
|
||||
+ Example: `REDIS_CONN_STRING=redis://default:redispw@localhost:49153`
|
||||
2. `SESSION_SECRET`: when set, a fixed session key will be used so that the logged-in users' cookie remains valid across system reboots.
|
||||
+ Example: `SESSION_SECRET=random_string`
|
||||
3. `SQL_DSN`: when set, the target SQL database will be used instead of SQLite.
|
||||
+ Example: `SQL_DSN=root:123456@tcp(localhost:3306)/atsflare`
|
||||
Default URL: `http://localhost:3000`
|
||||
|
||||
### Command line Arguments
|
||||
1. `--port <port_number>`: specify the port number, the default value is `3000`.
|
||||
+ Example: `--port 3000`
|
||||
2. `--log-dir <log_dir>`: specify the log dir, if not set, the log won't be saved.
|
||||
+ Example: `--log-dir ./logs`
|
||||
3. `--version`: print the version and exit.
|
||||
Notes:
|
||||
|
||||
* Replace `SESSION_SECRET` with a random string
|
||||
* Replace `latest` with a fixed version tag if needed, for example `ghcr.io/rain-kl/atsflare:v0.3.0`
|
||||
* SQLite data is persisted in the Docker volume `atsflare-data`
|
||||
* For source build and full deployment steps, see [docs/deployment.md](./docs/deployment.md)
|
||||
|
||||
### 1.1 Server environment variables
|
||||
|
||||
Common environment variables:
|
||||
|
||||
| Variable | Description | Default behavior |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | Server listen port | Defaults to `3000` |
|
||||
| `GIN_MODE` | Gin runtime mode | Runs in release mode unless set to `debug` |
|
||||
| `SESSION_SECRET` | Session signing secret; should be set explicitly in production | Falls back to the built-in default |
|
||||
| `SQLITE_PATH` | SQLite database file path | Uses the built-in SQLite path |
|
||||
| `SQL_DSN` | MySQL DSN; when set, MySQL is used instead of SQLite | Uses SQLite when unset |
|
||||
| `REDIS_CONN_STRING` | Redis connection string for session/rate-limit related features | Redis is disabled when unset |
|
||||
| `UPLOAD_PATH` | Upload directory path | Defaults to `upload` |
|
||||
| `AGENT_TOKEN` | Legacy/global Agent token compatibility setting | Not required in the current default setup |
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
export SESSION_SECRET='replace-with-random-string'
|
||||
export SQLITE_PATH='./atsflare.db'
|
||||
export GIN_MODE='release'
|
||||
export PORT='3000'
|
||||
```
|
||||
|
||||
### 2. Install Agent with Discovery Token
|
||||
|
||||
Use this for first-time node bootstrap. The Agent will auto-register with `discovery_token` and exchange it for a node-specific `agent_token`.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
### 3. Install Agent with Agent Token
|
||||
|
||||
Use this when the node has already been created in the control plane and you already have a dedicated `agent_token`.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--agent-token YOUR_AGENT_TOKEN
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
* Replace `--server-url` with your actual control plane address, for example `http://192.168.1.10:3000`
|
||||
* On Linux, the installer defaults to `/opt/atsflare-agent` and creates the `atsflare-agent` systemd service
|
||||
* Re-running the same command upgrades the Agent to the latest release
|
||||
|
||||
## Delivery channels
|
||||
|
||||
Current release outputs:
|
||||
|
||||
* Server binaries: GitHub Releases
|
||||
* Server Docker image: GitHub Container Registry at `ghcr.io/rain-kl/atsflare`
|
||||
* Agent binaries: GitHub Releases
|
||||
|
||||
## Documentation
|
||||
|
||||
See:
|
||||
|
||||
1. [docs/deployment.md](./docs/deployment.md)
|
||||
2. [docs/design.md](./docs/design.md)
|
||||
3. [docs/development-guidelines.md](./docs/development-guidelines.md)
|
||||
4. [docs/development-plan.md](./docs/development-plan.md)
|
||||
Reference in New Issue
Block a user