aheh/PrivyDrop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docker): elevate Docker one-click to top, add LE automation + SNI443, update flags and compose v2 commands

Browse Source 
- DEPLOYMENT_docker.md/zh-CN: Add top Quick Start (private/public/full), Let’s Encrypt auto issue/renew (webroot, zero downtime), SNI 443 default for full+domain, common flags (--with-sni443, --turn-port-range, --le-email), replace docker-compose with docker compose.
- README.md/zh-CN: Promote Docker one-click section to top and link to docs.
- DEPLOYMENT.md/zh-CN: Add audience/scope notice; point to Docker docs for recommended path.
- ROADMAP.md/zh-CN: Record recently completed (Docker, LE, SNI, TURN).
This commit is contained in:
david_bai
2025-10-07 22:22:49 +08:00
parent 7809373f88
commit 2bd09835b1
8 changed files with 179 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOYMENT.md
+10 -1
View File
@@ -1,4 +1,8 @@
# PrivyDrop Deployment Guide
# PrivyDrop Deployment Guide (Bare-Metal)
> Audience & Scope: This guide targets developers/operators who prefer a non-container (bare-metal) setup.
>
> Recommended: Prefer the one-click Docker deployment for simplicity and robustness, including auto HTTPS and TURN. See [Docker Deployment Guide](./docs/DEPLOYMENT_docker.md).
This guide provides comprehensive instructions for deploying the full-stack PrivyDrop application, including setting up Redis, a TURN server, the backend service, the frontend application, and configuring Nginx as a reverse proxy.
@@ -30,6 +34,7 @@ sudo bash backend/docker/env_install.sh
```
This script will automatically install:
- **Node.js v20** - Runtime environment
- **Redis Server** - Used for room management and caching
- **Coturn** - TURN/STUN server (optional, for NAT traversal)
@@ -38,6 +43,7 @@ This script will automatically install:
- **Certbot** - SSL certificate management
After installation, you can verify the services:
```bash
# Verify Node.js version
node -v
@@ -53,11 +59,13 @@ sudo systemctl status coturn
```
**Configuration Notes:**
- **Redis Configuration:** Default listening on `127.0.0.1:6379`, ensure your backend `.env` file includes correct `REDIS_HOST` and `REDIS_PORT`
- **TURN Service:** Optional configuration, PrivyDrop uses public STUN servers by default, only needed for extremely high NAT traversal requirements
- **Nginx:** Script installs official version and verifies stream module support
**TURN Server Firewall Configuration (if configuring TURN service):**
```bash
# Enable the Coturn service
sudo sed -i 's/#TURNSERVER_ENABLED=1/TURNSERVER_ENABLED=1/' /etc/default/coturn
@@ -68,6 +76,7 @@ sudo ufw reload
```
The ports seen via `sudo ufw app info Turnserver` are as follows:
- `3478,3479,5349,5350,49152:65535/tcp`
- `3478,3479,5349,5350,49152:65535/udp`
docs/DEPLOYMENT.zh-CN.md
+5 -1
View File
@@ -1,4 +1,8 @@
# Privydrop 部署指南
# Privydrop 部署指南（裸机部署）
> 说明与定位：本指南面向具备 Linux 运维能力的开发者，介绍“裸机（非容器）”部署方式。
>
> 推荐方案：优先使用“一键 Docker 部署”，更简单、更稳健，支持自动签发/续期证书与 TURN。详见 [Docker 部署指南](./docs/DEPLOYMENT_docker.zh-CN.md)。
本指南提供部署 Privydrop 全栈应用的全面说明，包括设置 Redis、TURN 服务器、后端服务、前端应用以及配置 Nginx 作为反向代理。
docs/DEPLOYMENT_docker.md
+54 -61
View File
@@ -1,6 +1,22 @@
# PrivyDrop Docker Deployment Guide
# PrivyDrop Docker One-Click Deployment (Recommended)
This guide provides a one-click Docker deployment solution for PrivyDrop, supporting both private and public network environments without complex manual configuration.
This guide provides a one-click Docker deployment for PrivyDrop. It supports both private and public networks, automates config/build/start, and provisions HTTPS certificates.
## 🚀 Quick Start (Top)
```bash
# Private LAN (no domain/public IP)
bash ./deploy.sh --mode private
# Public IP without domain (with TURN)
bash ./deploy.sh --mode public --with-turn
# Public domain (HTTPS + Nginx + TURN + SNI 443, auto-issue/renew certs)
bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn --le-email you@domain.com
```
- Requires Docker Compose v2 (command `docker compose`).
- In full mode, Let’s Encrypt (webroot) is auto-issued and auto-renewed (no downtime); SNI 443 multiplexing is enabled by default (`turn.your-domain.com` → coturn:5349; others → web:8443).
## 🎯 Deployment Advantages
@@ -34,9 +50,9 @@ Compared to traditional deployment methods, Docker deployment offers the followi
### Software Dependencies
- Docker 20.10+
- Docker Compose 2.0+ (or docker-compose 1.27+)
- curl (for health checks)
- openssl (for SSL certificate generation)
- Docker Compose 2.x (command `docker compose`)
- curl (for health checks, optional)
- openssl (cert tools; the script auto-installs certbot)
## 🚀 Quick Start
@@ -92,21 +108,21 @@ bash deploy.sh --mode public --with-turn
- ✅ Supports complex network environments
- ✅ Automatic NAT traversal configuration
### Full Mode
### Full Mode (full)
**Use Case**: Production environment, public servers with domain
```bash
bash deploy.sh --domain your-domain.com --mode full --with-nginx --with-turn
bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn --le-email you@domain.com
```
**Features**:
- ✅ HTTPS secure access
- ✅ Self-signed SSL certificates
- ✅ HTTPS secure access (Let’s Encrypt auto-issue/renew, zero downtime)
- ✅ Nginx reverse proxy
- ✅ Built-in TURN server
- ✅ Complete production environment configuration
- ✅ Built-in TURN server (default port range 49152-49252/udp)
- ✅ SNI 443 multiplexing (turn.<domain> → coturn:5349; others → web:8443)
- ✅ Complete production setup
> Tip: If your network uses carrier-grade NAT or proxy and is mis-detected as public, append `--mode private` to skip public-IP probing and force basic mode. When the detected LAN IP is not the one you expect, append `--local-ip 192.168.x.x` to override it explicitly.
@@ -131,19 +147,22 @@ HTTPS_PROXY=http://your-proxy:7890
NO_PROXY=localhost,127.0.0.1,backend,frontend,redis,coturn
```
`docker-compose` passes these values as build args; the Dockerfiles expose them as environment variables so `npm`/`pnpm` automatically reuse the proxy. Leave them blank if you don't need a proxy.
`docker compose` passes these values as build args; the Dockerfiles expose them as environment variables so `npm`/`pnpm` automatically reuse the proxy. Leave them blank if you don't need a proxy.
### Enable Specific Services
### Common Flags
```bash
# Enable only Nginx reverse proxy
bash deploy.sh --with-nginx
bash ./deploy.sh --with-nginx
# Enable only TURN server
bash deploy.sh --with-turn
# Enable TURN (recommended in public/full)
bash ./deploy.sh --with-turn
# Enable all services
bash deploy.sh --with-nginx --with-turn
# Explicitly enable SNI 443 (auto-enabled in full+domain; use --no-sni443 to disable)
bash ./deploy.sh --with-sni443
# Adjust TURN port range (default 49152-49252/udp)
bash ./deploy.sh --mode full --with-turn --turn-port-range 55000-55100
```
## 🌐 Access Methods
@@ -164,54 +183,55 @@ After deployment, the script automatically displays LAN access addresses:
Backend API: http://192.168.1.100:3001
```
### HTTPS Access (if enabled)
### HTTPS Access (full mode)
- **Secure Access**: https://localhost
- **Certificate Location**: `docker/ssl/ca-cert.pem`
- **Public HTTPS**: https://your-domain.com
- **Certificate Source**: Let’s Encrypt (auto issue/renew via webroot)
- **Runtime Location**: Copied to `docker/ssl/` and hot-reloaded
**Note**: When first accessing HTTPS, the browser will warn about an untrusted certificate. This is normal. You can:
Notes:
1. Click "Advanced" → "Continue to site"
2. Or import the `docker/ssl/ca-cert.pem` certificate into your browser
- First-time issuance happens automatically after Nginx:80 is up; then 443 is enabled and hot-reloaded.
- Renewal is automated: a deploy-hook copies renewed certs to `docker/ssl/` and reloads Nginx; coturn is HUP’ed/restarted for TLS as needed.
## 🔍 Management Commands
### View Service Status
```bash
docker-compose ps
docker compose ps
```
### View Service Logs
```bash
# View all service logs
docker-compose logs -f
docker compose logs -f
# View specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f redis
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f redis
```
### Restart Services
```bash
# Restart all services
docker-compose restart
docker compose restart
# Restart specific service
docker-compose restart backend
docker compose restart backend
```
### Stop Services
```bash
# Stop services but keep data
docker-compose stop
docker compose stop
# Stop services and remove containers
docker-compose down
docker compose down
```
### Complete Cleanup
@@ -237,7 +257,7 @@ bash deploy.sh --clean
```bash
# First try cleaning previous containers
bash deploy.sh --clean # or docker-compose down
bash deploy.sh --clean # or docker compose down
# If the port is still occupied, locate the process
sudo ss -tulpn | grep :3002
@@ -436,15 +456,6 @@ logs/
└── coturn/ # TURN server logs
```
### Monitoring Integration (optional)
Can integrate Prometheus + Grafana monitoring stack:
```bash
# Enable monitoring (planned)
bash deploy.sh --with-monitoring
```
## 🔄 Updates and Maintenance
### Update Application
@@ -498,21 +509,3 @@ bash deploy.sh --help
### Community Support
- GitHub Issues: Technical questions and bug reports
- GitHub Discussions: Usage discussions and feature suggestions
---
## 📝 Changelog
### v1.0.0 (Docker Version)
- ✅ Added Docker one-click deployment support
- ✅ Added health check APIs
- ✅ Added automatic environment detection and configuration generation
- ✅ Added multiple deployment modes
- ✅ Added comprehensive troubleshooting guide
- ✅ Support for private network deployment without public IP requirement
---
**🎉 Congratulations! You have successfully deployed PrivyDrop. Start enjoying secure, private file sharing!**
docs/DEPLOYMENT_docker.zh-CN.md
+58 -75
View File
@@ -1,6 +1,22 @@
# PrivyDrop Docker 部署指南
# PrivyDrop Docker 一键部署（推荐）
本指南提供 PrivyDrop 的 Docker 一键部署方案，支持内网和公网环境，无需复杂的手动配置。
本指南提供 PrivyDrop 的 Docker 一键部署方案，支持内网与公网，一次命令完成配置、构建、启动与证书自动化。
## 🚀 快速开始（置顶）
```bash
# 内网（无域名/无公网IP）
bash ./deploy.sh --mode private
# 公网IP（无域名），含 TURN
bash ./deploy.sh --mode public --with-turn
# 公网域名（HTTPS + Nginx + TURN + SNI 443 分流，自动申请/续期证书）
bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn --le-email you@domain.com
```
- 使用 Docker Compose V2（命令 `docker compose`）。
- full 模式自动申请 Let’s Encrypt 证书（webroot，无停机）并自动续期；默认启用 SNI 443 分流（`turn.your-domain.com` → coturn:5349，其余 → web:8443）。
## 🎯 部署优势
@@ -34,9 +50,9 @@
### 软件依赖
- Docker 20.10+
- Docker Compose 2.0+ (或 docker-compose 1.27+)
- curl (用于健康检查)
- openssl (用于 SSL 证书生成)
- Docker Compose 2.x（命令 `docker compose`）
- curl（用于健康检查，可选）
- openssl（用于证书工具，脚本会自动安装 certbot）
## 🚀 快速开始
@@ -48,18 +64,13 @@ git clone https://github.com/david-bai00/PrivyDrop.git
cd PrivyDrop
```
### 2. 一键部署
### 2. 一键部署（示例）
```bash
# 基础部署 (推荐新手)
bash deploy.sh
# 等待部署完成后访问
# http://localhost:3002
# 示例：公网域名（HTTPS + Nginx + TURN）
bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn --le-email you@domain.com
```
就是这么简单！🎉
## 📚 部署模式详解
### 基础模式 (默认)
@@ -92,20 +103,20 @@ bash deploy.sh --mode public --with-turn
- ✅ 支持复杂网络环境
- ✅ 自动配置 NAT 穿透
### 完整模式
### 完整模式（full）
**适用场景**: 生产环境、有域名的公网服务器
```bash
bash deploy.sh --domain your-domain.com --mode full --with-nginx --with-turn
bash ./deploy.sh --mode full --domain your-domain.com --with-nginx --with-turn --le-email you@domain.com
```
**特性**:
- ✅ HTTPS 安全访问
- ✅ 自签名 SSL 证书
- ✅ HTTPS 安全访问（Let’s Encrypt 自动签发/续期，无停机）
- ✅ Nginx 反向代理
- ✅ 内置 TURN 服务器
- ✅ 内置 TURN 服务器（默认端口段 49152-49252/udp，可覆盖）
- ✅ SNI 443 分流（turn.<domain> → coturn:5349，其余 → web:8443）
- ✅ 完整生产环境配置
> 提示：若家庭宽带/运营商代理导致脚本误判为公网环境，可追加 `--mode private` 强制跳过公网检测，按基础模式执行；如果自动识别到的局域网地址不是你想要的，可进一步追加 `--local-ip 192.168.x.x` 显式指定。
@@ -133,17 +144,20 @@ NO_PROXY=localhost,127.0.0.1,backend,frontend,redis,coturn
`docker-compose` 会把这些变量作为 build args 传递给前后端镜像，Dockerfile 中会自动设置为环境变量，从而让 `npm`/`pnpm` 使用代理。若无需代理，保持为空即可。
### 启用特定服务
### 常用开关
```bash
# 仅启用 Nginx 反向代理
bash deploy.sh --with-nginx
# 仅启用 Nginx
bash ./deploy.sh --with-nginx
# 仅启用 TURN 服务器
bash deploy.sh --with-turn
# 启用 TURN（public/full 建议）
bash ./deploy.sh --with-turn
# 启用所有服务
bash deploy.sh --with-nginx --with-turn
# 显式启用 SNI 443（full+domain 默认开启，可用 --no-sni443 关闭）
bash ./deploy.sh --with-sni443
# 调整 TURN 端口段（默认 49152-49252/udp）
bash ./deploy.sh --mode full --with-turn --turn-port-range 55000-55100
```
## 🌐 访问方式
@@ -179,39 +193,39 @@ bash deploy.sh --with-nginx --with-turn
### 查看服务状态
```bash
docker-compose ps
docker compose ps
```
### 查看服务日志
```bash
# 查看所有服务日志
docker-compose logs -f
docker compose logs -f
# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f redis
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f redis
```
### 重启服务
```bash
# 重启所有服务
docker-compose restart
docker compose restart
# 重启特定服务
docker-compose restart backend
docker compose restart backend
```
### 停止服务
```bash
# 停ิ止服务但保留数据
docker-compose stop
# 停止服务但保留数据
docker compose stop
# 停止服务并删除容器
docker-compose down
docker compose down
```
### 完全清理
@@ -237,7 +251,7 @@ bash deploy.sh --clean
```bash
# 方法1: 清理旧容器
bash deploy.sh --clean # 或 docker-compose down
bash deploy.sh --clean # 或 docker compose down
# 方法2: 查找并结束占用进程
sudo ss -tulpn | grep :3002
@@ -392,19 +406,15 @@ networks:
bash deploy.sh --mode full --with-nginx
```
## 🔒 安全配置
## 🔒 HTTPS 与安全
### SSL/TLS 配置
### 证书自动化（Let’s Encrypt）
1. **自签名证书** (默认):
full 模式自动申请并续期证书：
- 自动生成和配置
- 适用于内网和测试环境
- 证书位置: `docker/ssl/`
2. **Let's Encrypt 证书** (计划中):
- 自动申请和续期
- 适用于有域名的生产环境
- 首次签发：webroot 模式（无停机），系统证书保存在 `/etc/letsencrypt/live/<domain>/`，脚本复制到 `docker/ssl/` 并启用 443；
- 续期：certbot deploy-hook 自动复制至 `docker/ssl/`，并热重载 Nginx 与重载（或重启）coturn；
- 证书谱系（-0001/-0002）已自动适配，无需手动处理。
### 网络安全
@@ -436,15 +446,6 @@ logs/
└── coturn/ # TURN服务器日志
```
### 监控集成 (可选)
可以集成 Prometheus + Grafana 监控栈：
```bash
# 启用监控 (计划中)
bash deploy.sh --with-monitoring
```
## 🔄 更新和维护
### 更新应用
@@ -477,8 +478,8 @@ cp .env .env.backup
docker system prune -f
# 更新基础镜像
docker-compose pull
docker-compose up -d
docker compose pull
docker compose up -d
```
## 🆘 获取帮助
@@ -498,21 +499,3 @@ bash deploy.sh --help
### 社区支持
- GitHub Issues: 技术问题和 bug 报告
- GitHub Discussions: 使用交流和功能建议
---
## 📝 更新日志
### v1.0.0 (Docker 化版本)
- ✅ 新增 Docker 一键部署支持
- ✅ 新增健康检查 API
- ✅ 新增自动环境检测和配置生成
- ✅ 新增多种部署模式
- ✅ 新增完整的故障排除指南
- ✅ 支持内网部署，无需公网 IP
---
**🎉 恭喜！你已经成功部署了 PrivyDrop。开始享受安全、私密的文件分享吧！**