Skip to content

Commit 154d073

Browse files
ossrs-aiwinlinvip
ossrs-ai
authored and
winlinvip
committed
AI: Add more docs.
1 parent db236fd commit 154d073

File tree

5 files changed

+386
-58
lines changed

5 files changed

+386
-58
lines changed

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Key characteristics:
1313

1414
## Design Overview
1515

16-
See the "Design" section in @README.md for the complete architecture overview, including:
16+
See @doc/design.md for the complete architecture overview, including:
1717
- Stateless proxy architecture with built-in load balancing
1818
- Single Proxy Mode (memory-based)
1919
- Multi-Proxy Mode (Redis sync, AWS NLB)

‎README.md‎

Lines changed: 3 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -9,67 +9,13 @@ This is a common proxy for all media servers, to enable you to build a Origin Cl
99
for your media server.
1010

1111
However, SRS works with this proxy much better than other media servers, as the proxy
12-
can discover more details from SRS. And this proxy is the official solution to build
13-
an origin cluster for SRS. Please see [SRS Origin Cluster](https://ossrs.io/lts/en-us/docs/v7/doc/origin-cluster)
12+
can discover more details from SRS. And this proxy is the official solution to build
13+
an origin cluster for SRS. Please see [SRS Origin Cluster](https://ossrs.io/lts/en-us/docs/v7/doc/origin-cluster)
1414
for details.
1515

1616
## Design
1717

18-
**proxy-go** is a stateless media streaming proxy with built-in load balancing that enables building scalable origin clusters. The proxy itself acts as the load balancer, routing streams from clients to backend origin servers.
19-
20-
```
21-
Client → Proxy (with Load Balancer) → Backend Origin Servers
22-
```
23-
24-
Since the proxy is stateless, you can deploy multiple proxies behind a load balancer (like AWS NLB) for horizontal scaling:
25-
26-
```
27-
Client → AWS NLB → Proxy Servers → Backend Origin Servers
28-
```
29-
30-
**Single Proxy Mode**
31-
32-
Use case: Moderate amount of streams requiring multiple origin servers (each stream has few viewers). The total stream count is manageable by a single proxy server. Uses memory-based load balancing (no Redis needed).
33-
34-
```
35-
+--------------------+
36-
+-------+ Origin Server A +
37-
+ +--------------------+
38-
+
39-
+-----------------------+ + +--------------------+
40-
+ Proxy Server +------+-------+ Origin Server B +
41-
+ (Memory LB) + + +--------------------+
42-
+-----------------------+ +
43-
+ +--------------------+
44-
+-------+ Origin Server C +
45-
+--------------------+
46-
```
47-
48-
**Multi-Proxy Mode (Scalable)**
49-
50-
Use case: When a single proxy becomes a bottleneck. Supports a large number of streams across many origin servers, with limited viewers per stream. Redis is required for state synchronization between proxies.
51-
52-
```
53-
+-----------------------+
54-
+---+ Proxy Server A +------+
55-
+-----------------+ | +-----------+-----------+ +
56-
| AWS NLB +--+ | +
57-
+-----------------+ | (Redis Sync) + Origin Servers
58-
| +-----------+-----------+ +
59-
+---+ Proxy Server B +------+
60-
+-----------------------+
61-
```
62-
63-
**Complete Cluster (Edge + Proxy + Origins)**
64-
65-
Use case: Very large deployments with both numerous streams AND numerous viewers. Edge servers aggregate upstream connections - fetching one stream from upstream to serve multiple viewers, dramatically reducing load on proxy and origin servers.
66-
67-
```
68-
Edge Servers → Proxy Servers → Origin Servers
69-
(Proxy + Cache) (Proxy) (SRS/Media)
70-
```
71-
72-
> **Note**: Future edge servers will be implemented as proxy servers with caching enabled, creating a unified architecture where the same codebase serves both proxy and edge roles. The edge cache aggregates viewer connections, so thousands of viewers can watch the same stream while only requesting it once from upstream.
18+
Please see [Design](doc/design.md) for details.
7319

7420
William Yang<br/>
7521
June 23, 2025

‎doc/design.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Design
2+
3+
## Overview
4+
5+
**proxy-go** is a stateless media streaming proxy with built-in load balancing that enables building scalable origin clusters. The proxy itself acts as the load balancer, routing streams from clients to backend origin servers.
6+
7+
```
8+
Client → Proxy (with Load Balancer) → Backend Origin Servers
9+
```
10+
11+
Since the proxy is stateless, you can deploy multiple proxies behind a load balancer (like AWS NLB) for horizontal scaling:
12+
13+
```
14+
Client → AWS NLB → Proxy Servers → Backend Origin Servers
15+
```
16+
17+
## Deployment Modes
18+
19+
### Single Proxy Mode
20+
21+
**Use case**: Moderate amount of streams requiring multiple origin servers (each stream has few viewers). The total stream count is manageable by a single proxy server. Uses memory-based load balancing (no Redis needed).
22+
23+
**Architecture**:
24+
25+
```
26+
+--------------------+
27+
+-------+ Origin Server A +
28+
+ +--------------------+
29+
+
30+
+-----------------------+ + +--------------------+
31+
+ Proxy Server +------+-------+ Origin Server B +
32+
+ (Memory LB) + + +--------------------+
33+
+-----------------------+ +
34+
+ +--------------------+
35+
+-------+ Origin Server C +
36+
+--------------------+
37+
```
38+
39+
### Multi-Proxy Mode (Scalable)
40+
41+
**Use case**: When a single proxy becomes a bottleneck. Supports a large number of streams across many origin servers, with limited viewers per stream. Redis is required for state synchronization between proxies.
42+
43+
**Architecture**:
44+
45+
```
46+
+-----------------------+
47+
+---+ Proxy Server A +------+
48+
+-----------------+ | +-----------+-----------+ +
49+
| AWS NLB +--+ | +
50+
+-----------------+ | (Redis Sync) + Origin Servers
51+
| +-----------+-----------+ +
52+
+---+ Proxy Server B +------+
53+
+-----------------------+
54+
```
55+
56+
### Complete Cluster (Edge + Proxy + Origins)
57+
58+
**Use case**: Very large deployments with both numerous streams AND numerous viewers. Edge servers aggregate upstream connections - fetching one stream from upstream to serve multiple viewers, dramatically reducing load on proxy and origin servers.
59+
60+
**Architecture**:
61+
62+
```
63+
Edge Servers → Proxy Servers → Origin Servers
64+
(Proxy + Cache) (Proxy) (SRS/Media)
65+
```
66+
67+
> **Note**: Future edge servers will be implemented as proxy servers with caching enabled, creating a unified architecture where the same codebase serves both proxy and edge roles. The edge cache aggregates viewer connections, so thousands of viewers can watch the same stream while only requesting it once from upstream.

‎doc/protocol.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Protocol
2+
3+
## Backend Server Registration
4+
5+
The origin server can register itself to the proxy server, so the proxy server can load balance
6+
the backend servers.
7+
8+
### Default Backend Server (For Debugging)
9+
10+
The proxy can automatically register a default backend server for testing and debugging purposes, controlled by environment variables:
11+
12+
```bash
13+
# Enable default backend server
14+
PROXY_DEFAULT_BACKEND_ENABLED=on
15+
16+
# Default backend server configuration
17+
PROXY_DEFAULT_BACKEND_IP=127.0.0.1
18+
PROXY_DEFAULT_BACKEND_RTMP=1935
19+
PROXY_DEFAULT_BACKEND_HTTP=8080 # Optional
20+
PROXY_DEFAULT_BACKEND_API=1985 # Optional
21+
PROXY_DEFAULT_BACKEND_RTC=8000 # Optional (UDP)
22+
PROXY_DEFAULT_BACKEND_SRT=10080 # Optional (UDP)
23+
```
24+
25+
When enabled, the proxy automatically registers this default backend server at startup and sends heartbeats every 30 seconds to keep it alive. This is useful for:
26+
- Quick testing without setting up backend server registration
27+
- Development and debugging scenarios
28+
- Single-server deployments
29+
30+
### Automatic Registration
31+
32+
SRS 5.0+ has built-in support for automatic registration to the proxy server using the heartbeat feature. Configure SRS to send heartbeats to the proxy's System API:
33+
34+
```nginx
35+
# For example, conf/origin1-for-proxy.conf in SRS.
36+
heartbeat {
37+
enabled on;
38+
interval 9;
39+
url http://127.0.0.1:12025/api/v1/srs/register;
40+
device_id origin1;
41+
ports on;
42+
}
43+
```
44+
45+
When heartbeat is enabled:
46+
- SRS automatically registers itself on startup
47+
- Sends periodic heartbeats (default: every 30 seconds) to keep the registration alive
48+
- Proxy marks servers as unavailable if heartbeats stop (after 300 seconds)
49+
- No manual intervention required - fully automatic
50+
51+
This is the **recommended approach** for production deployments with SRS backend servers.
52+
53+
### Manual Registration API
54+
55+
For non-SRS backend servers or custom integrations, use the HTTP API directly:
56+
57+
```bash
58+
curl -X POST http://127.0.0.1:12025/api/v1/srs/register \
59+
-H "Connection: Close" \
60+
-H "Content-Type: application/json" \
61+
-H "User-Agent: curl" \
62+
-d '{
63+
"device_id": "origin2",
64+
"ip": "10.78.122.184",
65+
"server": "vid-46p14mm",
66+
"service": "z2s3w865",
67+
"pid": "42583",
68+
"rtmp": ["19352"],
69+
"http": ["8082"],
70+
"api": ["19853"],
71+
"srt": ["10082"],
72+
"rtc": ["udp://0.0.0.0:8001"]
73+
}'
74+
#{"code":0,"pid":"53783"}
75+
```
76+
77+
### Registration Fields
78+
79+
* `ip`: Mandatory, the IP of the backend server. Make sure the proxy server can access the backend server via this IP.
80+
* `server`: Mandatory, the server id of backend server. For SRS, it stores in file, may not change.
81+
* `service`: Mandatory, the service id of backend server. For SRS, it always changes when restarted.
82+
* `pid`: Mandatory, the process id of backend server. Used to identify whether process restarted.
83+
* `rtmp`: Mandatory, the RTMP listen endpoints of backend server. Proxy server will connect backend server via this port for RTMP protocol.
84+
* `http`: Optional, the HTTP listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-FLV or HTTP-TS protocol.
85+
* `api`: Optional, the HTTP API listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-API, such as WHIP and WHEP.
86+
* `srt`: Optional, the SRT listen endpoints of backend server. Proxy server will connect backend server via this port for SRT protocol.
87+
* `rtc`: Optional, the WebRTC listen endpoints of backend server. Proxy server will connect backend server via this port for WebRTC protocol.
88+
* `device_id`: Optional, the device id of backend server. Used as a label for the backend server.
89+
90+
### Listen Endpoint Format
91+
92+
The listen endpoint format is `port`, or `protocol://ip:port`, or `protocol://:port`, for example:
93+
94+
* `1935`: Listen on port 1935 and any IP for TCP protocol.
95+
* `tcp://:1935`: Listen on port 1935 and any IP for TCP protocol.
96+
* `tcp://0.0.0.0:1935`: Listen on port 1935 and any IP for TCP protocol.
97+
* `tcp://192.168.3.10:1935`: Listen on port 1935 and specified IP for TCP protocol.
98+
99+
### Integration Options Summary
100+
101+
There are three ways to register backend servers to the proxy:
102+
103+
1. **Automatic Registration (Recommended for Production)**
104+
- Use SRS 5.0+ with heartbeat feature
105+
- Fully automatic, no manual scripts needed
106+
- Self-healing: automatically re-registers if proxy restarts
107+
- See "Automatic Registration (SRS 5.0+ Heartbeat)" section above
108+
109+
2. **Manual Registration API**
110+
- For non-SRS media servers (nginx-rtmp, Node-Media-Server, etc.)
111+
- Requires custom registration script or service
112+
- More flexible for heterogeneous environments
113+
- See "Manual Registration API" section above
114+
115+
3. **Default Backend (Development/Testing Only)**
116+
- Quick setup via environment variables
117+
- No backend server configuration needed
118+
- Use for development, testing, and debugging
119+
- See "Default Backend Server (For Debugging)" section above

0 commit comments

Comments
 (0)