dekun/jiedian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add deployment guide and user manual for Hy2-only stack

Browse Source 
Expand DEPLOY.md, add GUIDE.md and docs index, and cross-link troubleshooting and client-import docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-06-28 00:28:41 +08:00
parent daa76b6b9e
commit 5704ab1a0a
6 changed files with 535 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOY.md
+174 -23
View File
@@ -1,41 +1,147 @@
# Ubuntu 部署指南
# 部署指南
仓库：[https://git.bz121.com/dekun/jiedian.git](https://git.bz121.com/dekun/jiedian.git)
本文档说明如何在 Ubuntu VPS 上部署 **jiedian**（Hysteria2 + Web 管理面板）。
| 项目 | 值 |
|------|-----|
| VPS IP | 你的 VPS 公网 IP |
| 域名 | 已解析到 VPS 的域名 |
| 管理面板 | `http://域名/<PANEL_PATH>/`（**必须 http**） |
| 项目 | 说明 |
|------|------|
| 仓库 | https://git.bz121.com/dekun/jiedian.git |
| 部署目录 | `/opt/jiedian` |
| 系统要求 | Ubuntu 22.04 / 24.04（root 或 sudo） |
| 协议 | Hysteria2（UDP 8443+） |
| 管理面板 | `http://域名/<PANEL_PATH>/`（**HTTP 80，不要用 HTTPS 访问面板**） |
---
## 安全组
## 一、部署前准备
| 端口 | 协议 | 用途 |
|------|------|------|
| 22 | TCP | SSH |
| 80 | TCP | ACME + 面板 |
| 8443–8499 | UDP | Hysteria2（多节点递增） |
### 1. 购买 VPS 并获取 root 登录
---
建议使用境外 VPS，带宽 ≥ 30Mbps。记录：
## 一键部署
- 公网 IP（写入 `.env` 的 `VPS_IP`）
- SSH 登录方式（密码或密钥）
### 2. 域名与 DNS
将域名 **A 记录** 解析到 VPS 公网 IP（用于 Hy2 TLS 证书与面板访问）：
```
your.domain.com → YOUR_VPS_IP
```
验证：
```bash
dig +short A your.domain.com
# 应返回 VPS IP
```
### 3. 云厂商安全组
在阿里云 / 腾讯云等控制台放行：
| 端口 | 协议 | 用途 | 必须 |
|------|------|------|------|
| 22 | TCP | SSH | 是 |
| 80 | TCP | ACME 证书验证 + 管理面板 | 是 |
| 8443–8499 | UDP | Hysteria2（多节点递增） | 是 |
> **重要**：每增加一个节点，Hy2 端口 +1（8443、8444、8445…）。安全组必须放行 **8443–8499/UDP** 整段，不能只开 8443。
### 4. 填写 `.env`
```bash
git clone https://git.bz121.com/dekun/jiedian.git /opt/jiedian
cd /opt/jiedian
cp .env.example .env
nano .env
```
| 变量 | 必填 | 说明 |
|------|------|------|
| `VPS_IP` | 是 | VPS 公网 IP |
| `DOMAIN` | 是 | 已解析到 VPS 的域名 |
| `ACME_EMAIL` | 是 | Let's Encrypt 申请证书邮箱 |
| `PANEL_USERNAME` | 否 | 面板登录用户名，默认 `admin` |
| `PANEL_PASSWORD` | 否 | 面板密码；留空则安装时自动生成 |
| `PANEL_PATH` | 否 | 面板 URL 路径；留空则自动生成如 `jiedian-a1b2c3d4` |
| `PANEL_ALLOW_IP` | 否 | 仅允许指定 IP 访问面板（可选） |
`CLASH_API_SECRET` 由 `install.sh` 自动生成，供面板读取连接统计，无需手动填写。
---
## 二、一键安装（新机器）
```bash
ssh root@YOUR_VPS_IP
apt update && apt install -y git
git clone https://git.bz121.com/dekun/jiedian.git /opt/jiedian
cd /opt/jiedian
cp .env.example .env # 填写 VPS_IP、DOMAIN、ACME_EMAIL
cp .env.example .env
# 编辑 .env 填写 VPS_IP、DOMAIN、ACME_EMAIL
bash scripts/install.sh
```
登录面板 → 添加节点 → 复制 **Hysteria2** 链接到客户端。
安装脚本会自动完成：
1. 安装 sing-box、nginx、Python 面板依赖
2. 配置 UFW 防火墙（22/80 TCP，8443–8499 UDP）
3. 通过 acme.sh 为 `DOMAIN` 申请 TLS 证书
4. 初始化 SQLite 节点库与默认管理员
5. 生成 sing-box 配置并启动服务
安装结束输出示例：
```
==========================================
管理面板: http://66.hyf2.cc/jiedian-xxxx/
面板路径: jiedian-xxxx
用户名: dekun
密码: xxxxx
==========================================
```
浏览器打开面板地址 → 登录 → **添加节点** → 复制 **Hysteria2** 链接到客户端。
客户端导入详见 [client-import.md](client-import.md)。
---
## 从旧版（含 VLESS）升级
## 三、部署后验证
```bash
# 服务状态
systemctl is-active sing-box jiedian-panel nginx
# sing-box 配置语法
sing-box check -c /etc/sing-box/config.json
# Hy2 端口监听（默认 8443，多节点还有 8444…）
ss -ulnp | grep 8443
# 面板可访问
PANEL_PATH=$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)
curl -I "http://$(grep ^DOMAIN= /opt/jiedian/.env | cut -d= -f2)/${PANEL_PATH}/login"
```
客户端导入 Hy2 链接后测速，应显示正常延迟（非 `-1`）。
---
## 四、已有 VPS 更新代码
```bash
cd /opt/jiedian
git pull
python3 scripts/render-server.py
systemctl restart sing-box jiedian-panel
```
### 从旧版（含 VLESS/Xray）升级到仅 Hy2
若你之前部署过带 VLESS Reality 的版本：
```bash
cd /opt/jiedian
@@ -43,16 +149,61 @@ git pull
sudo bash scripts/remove-vless.sh
```
会停用 Xray、更新面板，仅保留 Hy2。
该脚本会：
- 停止并禁用 Xray
- 重载 sing-box 配置
- 重启面板
- 删除防火墙 443 规则（可选）
完成后客户端 **删除所有 VLESS 节点**，仅从面板复制 `hy2://` 链接。
---
## 常用命令
## 五、增删节点后的配置重载
面板添加/删除节点时会 **后台自动** 重载 sing-box。若需手动执行：
```bash
systemctl status sing-box jiedian-panel
python3 /opt/jiedian/scripts/render-server.py
cd /opt/jiedian
python3 scripts/render-server.py
systemctl restart sing-box
```
客户端导入见 [client-import.md](client-import.md)。
---
## 六、卸载与重装
```bash
cd /opt/jiedian
bash scripts/uninstall.sh
# 保留 .env 与代码，清理 data/ 与 venv
bash scripts/install.sh
```
---
## 七、架构说明
```
浏览器 ──► Nginx:80/<PANEL_PATH>/ ──► Flask 管理面板
│
▼
render-server.py
│
▼
sing-box :8443+
Hysteria2（每节点独立端口 + 密码）
客户端 ── UDP 8443+ ──► sing-box
```
更多技术细节见 [STACK.md](STACK.md)。
---
## 八、常见问题
见 [troubleshooting.md](troubleshooting.md)。
日常使用见 [GUIDE.md](GUIDE.md)。
docs/GUIDE.md
+192
View File
@@ -0,0 +1,192 @@
# 使用说明
本文档面向日常使用 jiedian 的用户，说明管理面板、节点与客户端的基本操作。
---
## 一、项目是什么
**jiedian** 是一套自建代理方案：
- **服务端**：VPS 上运行 sing-box，提供 **Hysteria2（Hy2）** 协议
- **管理面板**：Web 界面管理节点、复制链接、查看在线与流量
- **客户端**：v2rayN（Windows）、v2rayNG（Android）、Shadowrocket（iOS）等导入 Hy2 链接即可使用
> 当前版本 **仅支持 Hysteria2**，不再提供 VLESS/Reality。
---
## 二、管理面板
### 访问地址
```
http://你的域名/<PANEL_PATH>/
```
- 必须使用 **HTTP**（端口 80），不要用 HTTPS
- `PANEL_PATH` 在安装时生成，保存在 VPS 的 `/opt/jiedian/.env` 中：
```bash
grep PANEL_PATH /opt/jiedian/.env
```
### 登录
使用 `.env` 中的 `PANEL_USERNAME` 和 `PANEL_PASSWORD`。
### 面板功能
| 功能 | 说明 |
|------|------|
| 节点列表 | 查看各设备节点状态、连接数、实时/累计流量 |
| 添加节点 | 为每台设备创建独立 Hy2 账号 |
| 复制链接 | 一键复制 `hy2://` 分享链接 |
| 删除节点 | 删除后对应链接立即失效（至少保留 1 个节点） |
---
## 三、节点与设备
### 一设备一节点（推荐）
每个节点包含：
- 独立的 **Hy2 密码**
- 独立的 **UDP 端口**（按创建顺序递增）
| 节点顺序 | Hy2 端口 | 示例 |
|----------|----------|------|
| 第 1 个 | 8443 | 手机 |
| 第 2 个 | 8444 | 电脑 |
| 第 3 个 | 8445 | 平板 |
### 添加节点
1. 面板点击 **「+ 添加节点」**
2. 输入名称（如「手机」「电脑」）
3. 等待约 5–10 秒页面刷新（后台重载 sing-box）
4. 点击 **「复制」** 获取 Hy2 链接
5. 在客户端 **从剪贴板导入**
### 不要共用链接
同一 `hy2://` 链接 **技术上可多台设备同时连**，但不建议：
- 流量统计无法区分设备
- 带宽互相抢占
- 链接泄露影响所有共用设备
---
## 四、客户端配置
详细步骤见 [client-import.md](client-import.md)。
### 快速步骤
1. 在面板复制 `hy2://...` 链接
2. 打开客户端 → **从剪贴板导入**
3. 设为活动节点并连接
### 链接格式
```
hy2://密码@域名:端口?sni=域名#节点名-Hy2
```
示例：
```
hy2://xxxx@66.hyf2.cc:8443?sni=66.hyf2.cc#默认节点-Hy2
```
**注意：**
- 地址是 **域名**（`66.hyf2.cc`），不是 IP
- **SNI** 与域名相同
- 端口以面板显示为准（多节点时 8444、8445…）
### 推荐客户端
| 平台 | 客户端 |
|------|--------|
| Windows | [v2rayN](https://github.com/2dust/v2rayN/releases) |
| Android | [v2rayNG](https://github.com/2dust/v2rayNG/releases) |
| iOS | Shadowrocket / Streisand |
| macOS | v2rayN / Nekoray / sing-box |
---
## 五、Hy2 稳定性说明
Hysteria2 基于 **UDP**，特点：
| 优点 | 说明 |
|------|------|
| 弱网表现好 | 高丢包环境下通常比 TCP 代理更流畅 |
| 部署简单 | 无需 Reality 密钥、SNI 等复杂参数 |
| 本方案已验证 | 同 VPS 下 Hy2 通常比 VLESS 更易连通 |
| 注意 | 说明 |
|------|------|
| UDP 依赖 | 部分网络可能对 UDP 限速，可换 WiFi/热点试 |
| 证书 | 依赖域名与 Let's Encrypt，acme.sh 会自动续期 |
| 安全组 | 必须放行 8443–8499/UDP |
---
## 六、日常维护
### 查看服务状态
```bash
systemctl status sing-box jiedian-panel
```
### 更新代码（VPS 上）
```bash
cd /opt/jiedian
git pull
python3 scripts/render-server.py
systemctl restart sing-box jiedian-panel
```
### 忘记面板密码
```bash
grep PANEL_PASSWORD /opt/jiedian/.env
# 或重新生成
bash /opt/jiedian/scripts/generate-keys.sh
systemctl restart jiedian-panel
```
### 换设备 / 丢链接
在面板找到对应节点，重新 **复制** Hy2 链接导入即可，无需改服务端。
### 删除旧设备
面板删除该节点 → 客户端删除对应配置。
---
## 七、安全建议
1. **不要公开分享**节点链接
2. 面板使用随机 `PANEL_PATH`，不要对外暴露
3. 可设置 `PANEL_ALLOW_IP` 限制面板访问来源
4. 不要将 `.env` 或节点链接提交到公开仓库
5. 定期 `git pull` 更新到最新版本
---
## 八、文档索引
| 文档 | 内容 |
|------|------|
| [DEPLOY.md](DEPLOY.md) | VPS 部署、升级、验证 |
| [client-import.md](client-import.md) | 各平台客户端导入 |
| [troubleshooting.md](troubleshooting.md) | 故障排查 |
| [STACK.md](STACK.md) | 技术架构 |
docs/README.md
+16
View File
@@ -0,0 +1,16 @@
# jiedian 文档
| 文档 | 适用对象 | 内容 |
|------|----------|------|
| **[DEPLOY.md](DEPLOY.md)** | 运维 / 首次部署 | VPS 安装、安全组、`.env`、升级、验证 |
| **[GUIDE.md](GUIDE.md)** | 日常使用 | 面板操作、节点管理、Hy2 说明、安全建议 |
| **[client-import.md](client-import.md)** | 客户端用户 | Windows / Android / iOS 导入 Hy2 链接 |
| **[troubleshooting.md](troubleshooting.md)** | 排错 | 连不上、面板打不开、迁移 |
| **[STACK.md](STACK.md)** | 开发者 | 组件分工、端口、配置生成 |
## 快速链接
- 仓库：https://git.bz121.com/dekun/jiedian.git
- 部署目录：`/opt/jiedian`
- 一键安装：`bash scripts/install.sh`
- 旧版去 VLESS：`bash scripts/remove-vless.sh`
docs/client-import.md
+44 -13
View File
@@ -1,28 +1,43 @@
# 客户端导入
部署完成后，在 **管理面板** 复制各节点的 `hy2://` 链接。
部署完成后，在 **管理面板** 复制各节点的 `hy2://` 链接导入客户端。
日常使用说明见 [GUIDE.md](GUIDE.md)。
---
## Windows（v2rayN）
1. 下载 [v2rayN](https://github.com/2dust/v2rayN/releases)
2. **服务器 → 从剪贴板导入批量 URL**，粘贴面板复制的 `hy2://` 链接
3. 设为活动服务器并连接
1. 下载 [v2rayN](https://github.com/2dust/v2rayN/releases)（含 Core 的 zip 版）
2. 在面板复制 `hy2://` 链接
3. **服务器 → 从剪贴板导入批量 URL**
4. 右键节点 → **设为活动服务器** → 开启系统代理或 TUN
**测速：** 应显示毫秒延迟，不是 `-1`。
---
## Android（v2rayNG）
1. 安装 [v2rayNG](https://github.com/2dust/v2rayNG/releases)（arm64-v8a）
2. **+ → 从剪贴板导入**
3. 连接后开启 VPN
1. 下载 [v2rayNG](https://github.com/2dust/v2rayNG/releases)（多数手机选 **arm64-v8a**）
2. 复制面板 Hy2 链接
3. 右上角 **+ → 从剪贴板导入**
4. 点击右下角 **V** 连接
5. **设置 → 路由设置 → 绕过局域网及大陆地址**（推荐）
---
## iOS（Shadowrocket / Streisand）
**+ → 从剪贴板导入** `hy2://` 链接。
1. 复制面板 `hy2://` 链接
2. **+ → 从剪贴板导入**（或 Scan QR）
3. 连接后测试网页访问
---
## macOS
与 Windows 类似，使用 v2rayN、Nekoray 或 sing-box，从剪贴板导入 Hy2 链接。
---
@@ -32,12 +47,28 @@
hy2://PASSWORD@DOMAIN:8443?sni=DOMAIN#名称-Hy2
```
第二节点端口为 **8444**，依此类推，以面板显示为准。
| 字段 | 说明 |
|------|------|
| PASSWORD | 节点独立密码（面板自动生成） |
| DOMAIN | `.env` 中的域名，**不是 IP** |
| 8443 | 第一个节点端口；第二节点 8444，依此类推 |
| sni | 与 DOMAIN 相同 |
**完整链接以面板「复制」为准。**
---
## 注意
## 注意事项
- **一设备一节点**，不要多人共用同一链接
- 多节点升级后请 **重新复制** Hy2 链接（端口可能变化）
- SNI 为域名（如 `66.hyf2.cc`），不是 IP
1. **一设备一节点**，不要长期多人共用同一链接
2. 增删节点后 **必须重新复制** 链接（端口可能变化）
3. 不要使用旧版 **VLESS** 节点（项目已移除 VLESS）
4. 不要分享链接到公开渠道
---
## 相关文档
- [GUIDE.md](GUIDE.md) — 面板与节点管理
- [DEPLOY.md](DEPLOY.md) — VPS 部署
- [troubleshooting.md](troubleshooting.md) — 连不上时排查
docs/troubleshooting.md
+62 -14
View File
@@ -3,43 +3,91 @@
## 服务检查
```bash
systemctl is-active sing-box jiedian-panel
systemctl is-active sing-box jiedian-panel nginx
sing-box check -c /etc/sing-box/config.json
ss -ulnp | grep 8443
ss -ulnp | grep 8443 # 默认 8443，多节点还有 8444…
ss -tlnp | grep :80 # Nginx 面板
```
---
## 常见问题
### Hy2 连不上
### Hy2 连不上 / 延迟 -1
1. 安全组放行 **8443–8499/UDP**
2. 域名解析到 VPS IP
3. 从面板 **重新复制** Hy2 链接（多节点端口 8443、8444…）
4. `systemctl restart sing-box`
**检查顺序：**
### 面板打不开
1. **安全组** 是否放行 `8443–8499/UDP`（不只 8443）
2. **域名** 是否解析到 VPS IP：`dig +short A 你的域名`
3. **证书** 是否存在：`ls /etc/sing-box/certs/fullchain.pem`
4. 从面板 **重新复制** Hy2 链接（增删节点后端口会变）
5. 重启 sing-box：`systemctl restart sing-box`
- 使用 **`http://域名/PANEL_PATH/`**，不要用 https
- 443 未用于面板，面板在 **80** 端口
**客户端核对：**
### 增删节点后 503
| 项 | 正确值 |
|----|--------|
| 地址 | 域名（如 `66.hyf2.cc`），不是 IP |
| SNI | 与域名相同 |
| 端口 | 面板显示的端口（8443 / 8444…） |
等 5–10 秒刷新；sing-box 重启期间可能短暂不可用。
### 面板打不开 / Invalid URL
### 从旧版 VLESS 迁移
- 使用 **`http://域名/PANEL_PATH/`**，不要用 `https://`
- 面板在 **80** 端口，不是 443
- 域名建议 **关闭 CDN**，仅 DNS 解析到 VPS
```bash
grep PANEL_PATH /opt/jiedian/.env
curl -I "http://$(grep ^DOMAIN= /opt/jiedian/.env | cut -d= -f2)/$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)/login"
```
### 多节点全部显示离线
1. 更新并重载：
```bash
cd /opt/jiedian && git pull
sudo bash scripts/remove-vless.sh
python3 scripts/render-server.py
systemctl restart sing-box jiedian-panel
```
2. 安全组放行 `8443–8499/UDP`
3. 各节点 **重新复制** Hy2 链接（第二节点端口 8444…）
### 添加/删除节点后白屏或 503
创建/删除节点会后台重启 sing-box，等 **5–10 秒** 刷新；新版前端会自动重试。
### 忘记面板密码
```bash
grep PANEL_PASSWORD /opt/jiedian/.env
# 或
bash /opt/jiedian/scripts/generate-keys.sh
systemctl restart jiedian-panel
```
### 从旧版 VLESS 迁移后客户端仍连不上
1. VPS 执行：`bash /opt/jiedian/scripts/remove-vless.sh`
2. 客户端 **删除所有 VLESS 节点**
3. 从面板 **仅导入 Hy2 链接**
---
## 端口一览
| 端口 | 协议 | 用途 |
|------|------|------|
| 22 | TCP | SSH |
| 80 | TCP | 面板 + ACME |
| 8443–8499 | UDP | Hysteria2 |
---
## 相关文档
- 部署：[DEPLOY.md](DEPLOY.md)
- 使用：[GUIDE.md](GUIDE.md)
- 客户端：[client-import.md](client-import.md)