PortWeave

Expose internal demos, preview apps, and personal sites through temporary public ports with FRP, a web control plane, and dynamic firewall automation.

PortWeave is a lightweight FRP-powered publishing layer for developers and teams who need to expose internal services without asking for permanent ingress, domain routing, or Nginx changes.

The Pain

Sometimes you just want to:

• put a demo online for review
• share a temporary preview link
• expose an internal API to a teammate or customer
• publish a small personal homepage from a restricted cluster

But the real world often looks like this:

• your cluster does not let you open arbitrary public ports
• you do not control Nginx or the edge gateway
• the service only needs to be reachable for a short time
• the workload runs inside a container or job, not a full VM
• hand-writing FRP configs and firewall rules is too manual

PortWeave is built for exactly that workflow.

What PortWeave Does

• publishes services directly through http://VPS_IP:REMOTE_PORT
• optionally publishes services through path URLs like http://VPS_IP:PANEL_PORT/SERVICE_PATH
• uses frps for TCP tunneling and a Web control plane for lifecycle management
• opens business ports only when needed and closes them automatically on offline, delete, timeout, or expiry
• generates frpc config automatically from a service token
• serves cached frpc binaries from the VPS panel so client machines do not have to download directly from GitHub
• supports both systemd hosts and non-systemd container/job environments
• supports multiple forwarded services on the same developer machine without path conflicts
• provides a bilingual Web UI with English as the default language

Top View

flowchart LR
    A[Developer Service<br/>demo / preview / homepage / API]
    B[frpc on dev machine]
    C[PortWeave Panel<br/>service registry / installer / firewall]
    D[frps on VPS]
    E[Public Visitor]

    A <-- local port --> B
    B <-- FRP tunnel --> D
    C -. generates config .-> B
    C -. opens/closes public port .-> D
    E -->|http://VPS_IP:REMOTE_PORT| D

Loading

Access Model

• Panel: http://VPS_IP:PANEL_PORT
• Installer: curl -fsSL http://VPS_IP:PANEL_PORT/install.sh | bash
• Business traffic:
  • path mode: http://VPS_IP:PANEL_PORT/SERVICE_PATH
  • port mode: http://VPS_IP:REMOTE_PORT

Architecture

• frps Handles TCP tunneling
• panel Handles the Web UI, generated installer scripts, generated frpc configs, service state, and dynamic firewall control

No domain name and no Nginx are required.

When to Use

• You need to publish a demo, preview app, or temporary homepage quickly
• Your environment does not allow permanent ingress changes
• You want a direct public port instead of domain-based routing
• You need service-level expiry, token-based access, and port lifecycle management
• Your workloads may run on plain hosts, containers, or jobs

When Not to Use

• You need a long-term, polished public edge with TLS termination and domain routing
• You already have a managed ingress controller, gateway, or reverse proxy workflow
• You need advanced L7 traffic management, OAuth, WAF, or multi-tenant edge policy
• You want a full platform mesh instead of lightweight point-to-point exposure

Deployment Flow

sequenceDiagram
    participant Admin as Admin
    participant Panel as PortWeave Panel
    participant Client as Dev Machine
    participant FRPS as frps on VPS
    participant Visitor as Public Visitor

    Admin->>Panel: Create service (name, local port, remote port, token, expiry)
    Panel->>Panel: Validate port and register service
    Panel->>Panel: Open remote port in firewall
    Client->>Panel: Run installer with token
    Panel-->>Client: Return cached frpc binary + generated frpc config
    Client->>FRPS: Connect through FRP tunnel
    Visitor->>FRPS: Access VPS_IP:REMOTE_PORT
    FRPS->>Client: Forward traffic to local service
    Panel->>Panel: Close port on offline, delete, timeout, or expiry

Loading

Quick Start

1. Create the private config directory from the safe public template:

git clone https://github.com/GZWSAMA/PortWeave.git
cd PortWeave
cp -r private.sample private

2. Edit:

• private/runtime.env
• private/frps.toml
• private/deployment.md

3. Start the stack:

docker-compose --env-file private/runtime.env up -d --build

The Compose file uses relative build and data paths, so the project can run from any directory.

Documentation

• English README: README.md
• 中文 README: README.zh-CN.md
• Usage Guide: USAGE.md
• 中文使用文档: USAGE.zh-CN.md
• Docker Deployment Guide: docs/DOCKER_DEPLOYMENT.md
• 中文 Docker 部署教程: docs/DOCKER_DEPLOYMENT.zh-CN.md
• Security Notes: SECURITY.md
• 中文安全说明: SECURITY.zh-CN.md
• Private Config Template: private.sample/README.md
• 中文私有配置模板: private.sample/README.zh-CN.md

Open-Source Safety

The repository keeps public-safe samples only:

• .env.example
• config/frps.toml
• private.sample/runtime.env
• private.sample/frps.toml
• development-only helper files under dev/

Do not upload:

• private/
• data/

Runtime Notes

• Long-lived public ports are normally only: PANEL_PORT and FRP_BIND_PORT
• the frps dashboard stays on loopback only by default
• business ports are opened only on demand

License

This project is released under the MIT License.