init nginx related database schema
This commit is contained in:
GW_MC
208
public/migration/doc/nginx-tables.md
Normal file
208
public/migration/doc/nginx-tables.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Migration Tables → nginx mapping
|
||||
|
||||
This document explains the purpose of each migration table added under `public/migration/src/migrations` and how the rows map to generated nginx configuration (HTTP `http {}` and `stream {}` contexts).
|
||||
|
||||
Summary of tables covered:
|
||||
|
||||
- `upstream`
|
||||
- `upstream_target`
|
||||
- `proxy_host`
|
||||
- `location`
|
||||
- `stream_service`
|
||||
- `access_list`
|
||||
- `access_list_entry`
|
||||
- `audit_log`
|
||||
|
||||
---
|
||||
|
||||
## `upstream`
|
||||
|
||||
Purpose: A named backend pool of servers. Shared by HTTP and stream services.
|
||||
|
||||
Key fields:
|
||||
|
||||
- `id`: UUID primary key
|
||||
- `name`: identifier used when generating nginx `upstream <name> {}`
|
||||
- `protocol`: `http` | `tcp` | `udp` — determines how nginx will use the pool
|
||||
- `algorithm`: load balancing strategy (`round_robin`, `least_conn`, `ip_hash`)
|
||||
- `sticky_session`: whether to enable sticky behavior when supported
|
||||
- `health_check`: optional JSON describing health probes
|
||||
|
||||
nginx mapping (HTTP):
|
||||
|
||||
```nginx
|
||||
upstream <name> {
|
||||
server 10.0.0.5:8080 weight=2;
|
||||
server 10.0.0.6:8080 backup;
|
||||
# optional LB settings generated from `algorithm` and `sticky_session`
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://<name>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
nginx mapping (stream):
|
||||
|
||||
```nginx
|
||||
stream {
|
||||
upstream <name> {
|
||||
server 10.0.0.5:3306;
|
||||
server 10.0.0.6:3306 backup;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 3306;
|
||||
proxy_pass <name>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes: `upstream.protocol` selects which block and directive forms to generate;
|
||||
|
||||
---
|
||||
|
||||
## `upstream_target`
|
||||
|
||||
Purpose: One row per backend server in an `upstream` pool.
|
||||
|
||||
Key fields:
|
||||
|
||||
- `upstream_id`: FK to `upstream`
|
||||
- `target_host`, `target_port`
|
||||
- `weight`, `is_backup`, `enabled`
|
||||
|
||||
nginx mapping: each row becomes a `server` line in the generated `upstream` block (weights and backup flags applied). Disabled targets are omitted.
|
||||
|
||||
Example generated line:
|
||||
|
||||
```nginx
|
||||
server 10.0.0.5:8080 weight=3;
|
||||
server 10.0.0.6:8080 backup;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `proxy_host`
|
||||
|
||||
Purpose: Represents an HTTP(S) host (a top-level `server` block in nginx `http` context).
|
||||
|
||||
Key fields:
|
||||
|
||||
- `domain`: `server_name` value (may be a wildcard)
|
||||
- `listen_port`: port to listen on (80/443)
|
||||
- `scheme`: http|https (informs UI; TLS handled elsewhere)
|
||||
- `forward_host/forward_port` or `default_upstream_id`: host-level forwarding fallback
|
||||
- `preserve_host_header`: whether to forward original `Host` header
|
||||
- `enable_websocket`: toggles websocket header handling
|
||||
- `meta`: JSON for optional host-level settings (timeouts, client_max_body_size, custom snippets)
|
||||
|
||||
nginx mapping (host-level default):
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen <listen_port>;
|
||||
server_name <domain>;
|
||||
|
||||
# host-level fallback if no matching location
|
||||
location / {
|
||||
proxy_pass http://<default_upstream_name>;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If `forward_host`/`forward_port` is set instead of `default_upstream_id`, generate `proxy_pass http://forward_host:forward_port;`.
|
||||
|
||||
`meta` entries are injected into the `server` block (careful: snippets can break reloads).
|
||||
|
||||
---
|
||||
|
||||
## `location`
|
||||
|
||||
Purpose: Path-level routing (`location` blocks inside a `server`). More specific than `proxy_host` default.
|
||||
|
||||
Key fields:
|
||||
|
||||
- `host_id`: FK to `proxy_host`
|
||||
- `path`: `location` match (e.g., `/api`, `~^/assets/`)
|
||||
- `match_type`: `prefix` | `exact` | `regex`
|
||||
- `upstream_id` or `proxy_pass_host`/`proxy_pass_port`
|
||||
- `allowed_methods`: optional method whitelist
|
||||
- `custom_config`: raw nginx snippet inserted inside the `location`
|
||||
|
||||
nginx mapping:
|
||||
|
||||
```nginx
|
||||
location /api {
|
||||
proxy_pass http://api_upstream;
|
||||
# optional custom_config injected here
|
||||
}
|
||||
```
|
||||
|
||||
Ordering and match type produce correct nginx `location` selection semantics; `order` field can break ties for equal specificity.
|
||||
|
||||
---
|
||||
|
||||
## `stream_service`
|
||||
|
||||
Purpose: A TCP/UDP service in nginx `stream` context — corresponds to a `server` block inside `stream {}`.
|
||||
|
||||
Key fields:
|
||||
|
||||
- `listen_host`, `listen_port`
|
||||
- `protocol`: `tcp` | `udp`
|
||||
- `mode`: `direct` | `upstream` (direct forwards to `forward_host:forward_port`, `upstream` uses `upstream_id` pool)
|
||||
- `preserved_client_ip`: whether to enable proxy_protocol or other client-ip forwarding
|
||||
- `meta`: JSON for advanced stream options (ssl_preread, proxy_timeout, buffer sizes)
|
||||
|
||||
nginx mapping (stream):
|
||||
|
||||
```nginx
|
||||
stream {
|
||||
upstream <name> {
|
||||
server 10.0.0.5:3306;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 3306;
|
||||
proxy_pass <name>; # or proxy_pass 10.0.0.10:3306 for direct
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes: Stream services bypass HTTP processing. Use `meta` for `proxy_protocol` and `ssl_preread` toggles.
|
||||
|
||||
---
|
||||
|
||||
## `access_list` and `access_list_entry`
|
||||
|
||||
Purpose: Nameable allow/deny lists for IP/CIDR or other entry types that can be applied to hosts/locations/stream services.
|
||||
|
||||
Key fields (access_list): `id`, `name`, `description`.
|
||||
Key fields (entry): `access_list_id`, `entry_type` (e.g., `allow`, `deny`, `note`), `value` (IP or CIDR), `comment`.
|
||||
|
||||
nginx mapping (HTTP example):
|
||||
|
||||
```nginx
|
||||
location /admin {
|
||||
allow 10.0.0.0/24;
|
||||
deny all;
|
||||
proxy_pass http://admin_upstream;
|
||||
}
|
||||
```
|
||||
|
||||
nginx mapping (stream example):
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 3306;
|
||||
allow 10.0.0.0/24;
|
||||
deny all;
|
||||
proxy_pass backend_pool;
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user