arulriyadi/tunnela

# Tunnela 一个面向生产环境的 [WGDashboard](https://github.com/WGDashboard/WGDashboard) 分支，专注于部署的附加功能（Nginx + Gunicorn Unix socket，扩展文档和 UI 调整）。它提供了一个 **Web UI**，用于管理 **WireGuard** 接口、peer、QR 配置及相关操作。 印尼语的分步指南位于 [`src/install-step-by-step.md`](src/install-step-by-step.md) 及相关的 `implementasi-*.md` 文件中。 ## 截图 ### Dashboard **主页 — WireGuard 概览** — 接口/peer 摘要、累计流量、**系统状态**（CPU、内存、存储、swap）、**网络吞吐量**图表（所有接口）、服务器信息以及**网络流**（peer → 隧道 → Internet）。  **客户端 — 列表管理** — 24小时网络概览、各配置的流量表、总流量快照，以及带有各 peer 统计信息的可搜索 peer 列表。  ### 设置 **日期与时间、监听模式 & systemd** — 服务器时区、**Gunicorn** 监听模式（直接 TCP 还是用于 Nginx 的 **Unix socket**）、socket 路径，以及用于应用内重启的可选 **systemd** unit 名称。  **Nginx 反向代理 & 客户端统计** — 用于 **Nginx** 的部署代码片段 / 反向代理卡片，以及**客户端**网络概览 / 统计信息配置。  ## 架构 ``` Browser → [ Nginx ] → Gunicorn (TCP or Unix socket) → Flask (dashboard.py) ↓ ↓ TLS / HTTP SQLAlchemy → SQLite | PostgreSQL | MySQL ↓ wg / wg-quick (host) ``` | 层级 | 职责 | |-------|------------------| | **反向代理** (可选) | TLS 终止、向用户提供 HTTP(S)；在使用 Unix socket 模式时，`proxy_pass` 到 Gunicorn。 | | **Gunicorn** | WSGI 服务器；绑定 `app_ip:app_port` (直接) 或 Unix socket (`nginx_socket`)。 | | **Flask 应用** (`dashboard.py`) | HTTP API、会话、编排；加载 `modules/*` 服务。 | | **领域模块** | WireGuard / AmneziaWG 配置、peer、客户端、任务、OIDC、插件 — 业务逻辑。 | | **持久化** | 每个逻辑数据库名称对应一个 SQLAlchemy 引擎（PostgreSQL 下为 `wgdashboard`、`wgdashboard_job`、`wgdashboard_log`）。 | | **宿主操作系统** | WireGuard 工具、`/etc/wireguard`、用于从 UI 重启的可选 systemd unit。 | ## 项目结构 ``` tunnela/ ├── README.md ├── SUMMARY.md ├── templates/ │ └── wg-dashboard.ini.template # Reference INI (no secrets) └── src/ ├── dashboard.py # Flask app entry ├── gunicorn.conf.py ├── wgd.sh # install | start | stop | restart | debug ├── requirements.txt ├── modules/ # Core Python packages (config, WG, clients, …) ├── static/ │ ├── app/ # Vue admin UI (source) │ └── dist/ # Built admin/client assets (prebuilt in repo) ├── locales/ ├── install-step-by-step.md ├── implementasi-nginx-gunicorn-socket.md ├── sudoers.wgdashboard.example └── wg-dashboard.service # Example systemd unit ``` 运行时路径（在本地创建，不提交）：`venv/`、`db/`、`log/`、`wg-dashboard.ini`、`run/` (socket 父目录) 等。请参阅 [`.gitignore`](.gitignore)。 ## 快速开始 ### 前置条件 | 需求 | 说明 | |-------------|--------| | **Linux** | Debian/Ubuntu、RHEL 系列、Alpine (实验性)、Arch — 由 `wgd.sh` 支持。 | | **Python** | **3.10、3.11 或 3.12**（由安装器强制执行）。 | | **sudo** | 在默认设置中用于包安装、`/etc/wireguard` 以及 Gunicorn 生命周期管理。 | | **网络** | `./wgd.sh install` 期间需要访问 PyPI 的出站 HTTPS 连接。 | | **WireGuard** | 如果缺失，由脚本安装 (`wg`、`wg-quick`)。 | 可选：用于生产环境的 **PostgreSQL** 或 **MySQL**（参见 [数据库](#database-postgresql)）；仅当你重新构建 Vue 管理界面 (`static/app`) 时才需要 **Node.js**。 ### 1. 克隆 ``` git clone https://github.com/arulriyadi/tunnela.git cd tunnela ``` SSH： ``` git clone git@github.com:arulriyadi/tunnela.git cd tunnela ``` ### 2. 安装 (从 `src/`) ``` cd src chmod +x wgd.sh ./wgd.sh install ``` 日志：`src/log/install.txt`。 ### 3. 运行 ``` ./wgd.sh start ``` 默认 UI URL：`http://:10086`（在 `wg-dashboard.ini` → `[Server]` 中调整 `app_port`）。 ### 4. 首次登录 首次登录后请更改默认的管理员密码。使用 [`templates/wg-dashboard.ini.template`](templates/wg-dashboard.ini.template) 作为参考；本地的 `wg-dashboard.ini` 已被 gitignore。 ## `wgd.sh` 命令 | 命令 | 描述 | |---------|-------------| | `./wgd.sh install` | 创建 venv，安装 `requirements.txt`、WireGuard 工具以及初始文件夹。 | | `./wgd.sh start` | 在后台启动 Gunicorn。 | | `./wgd.sh stop` | 停止 Gunicorn。 | | `./wgd.sh restart` | 停止然后再启动。 | | `./wgd.sh debug` | 在前台运行 Flask 应用（开发用）。 | | `./wgd.sh update` | 更新流程（上游 WGDashboard 风格；在分支上使用前请先审查）。 | ## 环境变量 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `CONFIGURATION_PATH` | *(未设置 → `.`)* | 脚本使用的 `wg-dashboard.ini`、`db/`、`run/`、Lets Encrypt 路径的基础路径。 | | `WGDASHBOARD_SYSTEMD_UNIT` | *(可选)* | 覆盖 `[Server] systemd_unit`，用于从 UI “重启服务”。 | | `ENVIRONMENT` | `develop` | 由 `wgd.sh` 使用（例如 certbot 路径行为）。 | ## 配置文件 | 文件 | 用途 | |------|---------| | `src/wg-dashboard.ini` | 主应用配置（`[Server]`、`[Database]`、`[Account]` 等）。首次启动时创建/合并。 | | `src/ssl-tls.ini` | TLS 证书路径（可选）。从 `ssl-tls.ini.example` 复制。 | | `src/certbot.ini` | Certbot 设置（可选）。从 `certbot.ini.example` 复制。 | 密钥**绝对不能**被提交；请使用模板和 `.example` 文件。 ## 数据库 (PostgreSQL) 如果 `[Database] type = postgresql`，应用期望有 **三个** 逻辑数据库（如果数据库角色具有 `CREATEDB` 权限则会自动创建，或者手动创建它们）： | 数据库 | 角色 | |----------|------| | `wgdashboard` | 主要应用数据 | | `wgdashboard_job` | Peer 任务 | | `wgdashboard_log` | Dashboard 日志记录 | 为应用角色授予 `CREATEDB` 权限，或者预先创建这三个数据库并分配所有权。如果看到 `permission denied to create database`，请查阅项目文档中的相关讨论。 ## API 接口 (概览) Flask 应用将路由挂载在可配置的 **`app_prefix`** 下（通常为空）。典型模式： | 区域 | 模式 | 认证 | |------|---------|------| | UI + JSON API | `GET/POST {APP_PREFIX}/api/...` | 根据路由使用 Session / API key / OIDC | | 静态管理界面 | `GET {APP_PREFIX}/...` | 登录后按配置提供服务 | 要获取完整列表，请检查 `dashboard.py` 和路由装饰器。代码树中没有单独的 OpenAPI 文件。 ## Nginx 与 Unix socket 要将 Tunnela 置于使用 Unix socket 的 Nginx 之后，请在 `wg-dashboard.ini` 中设置： - `app_listen_mode = nginx_socket` - `gunicorn_socket_path` = `.sock` 文件的绝对路径 当进程不是以 root 用户运行时，请参阅 **[src/implementasi-nginx-gunicorn-socket.md](src/implementasi-nginx-gunicorn-socket.md)** 和 **[src/sudoers.wgdashboard.example](src/sudoers.wgdashboard.example)** 以了解部署和免密码 `sudo` 设置。 ## 重新构建管理 UI (可选) ``` cd src/static/app npm ci # or npm install npm run build ``` 已提交的 `src/static/dist` 允许在没有 Node 环境的生产服务器上进行读取和运行。 ## 设计决策 | 决策 | 理由 | |----------|-----------| | **单体 Flask 应用** | 与上游 WGDashboard 匹配；具有清晰 `modules/` 边界的单进程模型。 | | **使用 INI + 环境变量进行配置** | 仓库中没有强制的 `.env`；`wg-dashboard.ini` 是运维人员的事实来源。 | | **多个 SQL 数据库 (名称)** | 任务和日志与核心 schema 分离；SQLite 使用 `db/` 下的文件。 | | **预构建的 `static/dist`** | 在没有前端工具链的服务器上实现更快的部署。 | | **分支特定的文档位于 `src/`** | 操作手册（Nginx、安装）与代码放在一起。 | ## 故障排除 | 症状 | 检查项 | |---------|--------| | 安装失败 | `src/log/install.txt`、Python 版本、sudo 权限、与 PyPI 的网络连接。 | | PostgreSQL `CREATE DATABASE` 被拒绝 | 角色需要 `CREATEDB` 权限或预创建 `wgdashboard`、`wgdashboard_job`、`wgdashboard_log`。 | | 无法在浏览器中打开 | 防火墙、`app_ip` / `app_port`、Gunicorn 是否正在监听。 | | 从 UI 部署 Nginx 失败 | 进程用户、`sudoers` 条目、`sudoers.wgdashboard.example` 中的路径。 | ## 许可证 遵循上游 **WGDashboard** 的许可协议（参见源码头文件；根据上游为 **Apache-2.0**）。 ## 链接 | 文档 | 描述 | |-----|-------------| | [install-step-by-step.md](src/install-step-by-step.md) | 清单、流程、INI 部分 (印尼语)。 | | [implementasi-nginx-gunicorn-socket.md](src/implementasi-nginx-gunicorn-socket.md) | Nginx + socket 部署。 | | [WGDashboard-version-check-flow.txt](docs/WGDashboard-version-check-flow.txt) | GitHub release 检查 + `update_github_repo` / 环境变量 (参考)。 | | [Tunnela-fork-version-check-github.txt](docs/Tunnela-fork-version-check-github.txt) | 针对发布和 GitHub 的分支检查清单。 | | [UPDATE-v4.3.3.md](UPDATE-v4.3.3.md) | v4.3.3 的发布说明（功能、文件、构建）。 | | [UPDATE-v4.3.4.md](UPDATE-v4.3.4.md) | v4.3.4 的发布说明（系统和服务器信息、API、语言环境）。 | | [UPDATE-v4.4.1.md](UPDATE-v4.4.1.md) | v4.4.1 的发布说明（防火墙规则优先级、nft sort_order、暗色表格）。 | | [UPDATE-v4.4.4.md](UPDATE-v4.4.4.md) | v4.4.4 的发布说明（审计日志、SG 批量 peer、孤立数据清理）。 | | [UPDATE-v4.4.5.md](UPDATE-v4.4.5.md) | v4.4.5 的发布说明（恢复备份修复、peer 数量预览、fetchPost UX）。 | **TL;DR：** `cd src` → `./wgd.sh install` → `./wgd.sh start` → 打开 `http://host:10086` → 确保凭据和数据库安全。

标签：Flask, Nginx, TCP SYN 扫描, VPN, Web UI, WireGuard, 运维管理