部署指南¶

在各种环境中部署 Shortener 服务器的完整指南。

目录¶

概述
前提条件
部署方法
Docker 部署
Systemd 部署
手动部署
云部署
反向代理设置
SSL/TLS 配置
监控
备份和恢复

概述¶

Shortener 服务器可以通过多种方式部署：

Docker - 推荐用于大多数场景
Systemd - 用于传统 Linux 部署
手动 - 用于自定义设置
云 - AWS、GCP、Azure 等

前提条件¶

系统要求¶

CPU：最少 1 核，推荐 2+ 核
内存：最少 512MB，推荐 1GB+
磁盘：最少 1GB，推荐 10GB+
操作系统：Linux（Ubuntu 20.04+、Debian 11+、CentOS 8+ 等）

软件要求¶

Rust：1.90+（从源码构建）
Docker：20.10+（Docker 部署）
PostgreSQL：12+ 或 MySQL：8.0+（可选，生产环境）
Redis：6.0+ 或 Valkey：7.0+（可选，缓存）

部署方法¶

快速比较¶

方法	难度	隔离性	可移植性	最适合
Docker	简单	高	高	大多数部署
Systemd	中等	低	低	传统 Linux
手动	困难	低	低	自定义设置
云	简单	高	高	可扩展部署

Docker 部署¶

Docker 是推荐的部署方式，提供了简单的设置和良好的隔离性。

详细的 Docker 部署说明请参阅 Docker 部署指南，包括：

开发和生产环境配置
Docker Compose 设置
多数据库支持
环境变量配置
数据持久化
健康检查和监控

快速开始¶

# 克隆仓库
git clone https://github.com/jetsung/shortener.git
cd shortener

# 使用 Docker Compose 启动
docker compose up -d

更多详细信息请查看 Docker 部署指南。

创建环境变量文件（生成随机口令，供配置 password_hash 使用）：

cat > .env << EOF
DATABASE__URL=postgres://shortener:your_secure_password@postgres:5432/shortener
CACHE__URL=redis://:your_redis_password@redis:6379/0
API_KEY=$(openssl rand -base64 32)
OIDC__CLIENT_SECRET=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 48)
EOF

管理员登录口令同样随机生成，并用 shortener-server hash-password 转为 Argon2id 哈希后填入配置的 admin.password_hash：

shortener-server hash-password --password "$(openssl rand -base64 16)"

启动服务：

docker compose --env-file .env up -d

验证部署：

# 检查容器状态
docker compose ps

# 检查日志
docker compose logs -f shortener-server

# 测试 API
curl http://localhost:8080/go/

详细说明请参阅 Docker 部署指南。

Systemd 部署¶

安装¶

构建二进制文件：

cargo build --release -p shortener-server

安装 DEB 包（推荐）：

# 下载并安装 DEB 包
sudo apt install ./shortener-server_*.deb

或手动安装：

cd deploy/systemd
sudo ./install.sh

这将： - 复制二进制文件到 /usr/local/bin/ - 创建配置目录 /opt/shortener/config/ - 创建数据目录 /opt/shortener/data/ - 创建日志目录 /opt/shortener/logs/ - 创建 systemd 服务文件 - 创建 shortener 用户和组

配置服务：

sudo vim /opt/shortener/config/config.toml

配置数据库路径：

[database]
url = "sqlite:///opt/shortener/data/shortener.db?mode=rwc"

启动服务：

sudo systemctl start shortener-server
sudo systemctl enable shortener-server

验证：

sudo systemctl status shortener-server
sudo journalctl -u shortener-server -f

服务管理¶

# 启动
sudo systemctl start shortener-server

# 停止
sudo systemctl stop shortener-server

# 重启
sudo systemctl restart shortener-server

# 状态
sudo systemctl status shortener-server

# 启用自动启动
sudo systemctl enable shortener-server

# 查看日志
sudo journalctl -u shortener-server -f

手动部署¶

从源码构建¶

# 克隆仓库
git clone https://github.com/jetsung/shortener.git
cd shortener

# 构建发布版本
cargo build --release -p shortener-server

# 二进制文件位置
ls -lh target/release/shortener-server

设置目录¶

# 创建目录
sudo mkdir -p /opt/shortener/config
sudo mkdir -p /opt/shortener/data
sudo mkdir -p /opt/shortener/logs

# 复制文件
sudo cp target/release/shortener-server /usr/local/bin/
sudo cp config.toml /opt/shortener/config/

# 设置权限
sudo chown -R shortener:shortener /opt/shortener

创建用户¶

sudo useradd -r -s /bin/false shortener

手动运行¶

# 以 shortener 用户运行
sudo -u shortener /usr/local/bin/shortener-server

# 或使用自定义配置
sudo -u shortener /usr/local/bin/shortener-server --config /opt/shortener/config/config.toml

云部署¶

AWS¶

EC2 部署¶

启动 EC2 实例（Ubuntu 22.04 LTS）
安装 Docker：

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker ubuntu

部署应用：

git clone https://github.com/jetsung/shortener.git
cd shortener
docker compose up -d

RDS 数据库¶

[database]
url = "postgres://shortener:${DB_PASSWORD}@shortener.xxxxx.us-east-1.rds.amazonaws.com:5432/shortener?sslmode=require"

ElastiCache Redis¶

[cache]
enabled = true
url = "redis://:${REDIS_PASSWORD}@shortener.xxxxx.cache.amazonaws.com:6379/0"

Google Cloud Platform¶

Compute Engine¶

类似于 AWS EC2 部署。

Cloud Run¶

构建容器：

gcloud builds submit --tag gcr.io/PROJECT_ID/shortener-server

部署到 Cloud Run：

gcloud run deploy shortener-server \
  --image gcr.io/PROJECT_ID/shortener-server \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

反向代理设置¶

完整的外部 nginx 配置（专用短域名、透传头说明、可选缓存压缩）请参阅统一镜像部署指南 - 外部 Nginx 反向代理。

Nginx¶

upstream shortener {
    server localhost:8080;
    keepalive 32;
}

server {
    listen 80;
    server_name short.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name short.example.com;

    ssl_certificate /etc/letsencrypt/live/short.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/short.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://shortener;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

上述 Connection $connection_upgrade 依赖 http{} 层的 map（完整说明见 DOCKER_AIO.md）；不需要 WebSocket 时可直接写死 proxy_set_header Connection ""。

Caddy¶

short.example.com {
    reverse_proxy localhost:8080
}

SSL/TLS 配置¶

Let's Encrypt 与 Certbot¶

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d short.example.com

# 自动续期
sudo certbot renew --dry-run

监控¶

健康检查¶

# 检查服务器是否运行
curl http://localhost:8080/go/

日志¶

# 查看日志（Docker）
docker compose logs -f shortener

# 查看日志（Systemd）
sudo journalctl -u shortener-server -f

# 查看日志（手动）
tail -f /var/log/shortener/shortener.log

备份和恢复¶

数据库备份¶

PostgreSQL¶

# 备份
pg_dump -U shortener -h localhost shortener > backup.sql

# 恢复
psql -U shortener -h localhost shortener < backup.sql

MySQL¶

# 备份
mysqldump -u shortener -p shortener > backup.sql

# 恢复
mysql -u shortener -p shortener < backup.sql

SQLite¶

# 备份
sqlite3 /opt/shortener/data/shortener.db ".backup backup.db"

# 恢复
cp backup.db /opt/shortener/data/shortener.db
sudo chown shortener:shortener /opt/shortener/data/shortener.db

配置和数据备份¶

# 备份整个 shortener 目录
sudo tar czf shortener-backup-$(date +%Y%m%d).tar.gz /opt/shortener/

# 恢复
sudo tar xzf shortener-backup-20250117.tar.gz -C /
sudo chown -R shortener:shortener /opt/shortener

故障排除¶

服务器无法启动¶

检查配置：
```
shortener-server --config /opt/shortener/config/config.toml
```
服务端提供 init 与 hash-password 两个子命令：init 生成默认配置，hash-password 生成 Argon2id 口令哈希。运行服务前可用 shortener-server init 检查配置生成逻辑。

检查日志：

sudo journalctl -u shortener-server -n 50

检查端口可用性：
```
sudo lsof -i :8080
```

数据库连接问题¶

测试连接：

# PostgreSQL
psql -U shortener -h localhost -d shortener

# MySQL
mysql -u shortener -h localhost -p shortener

检查防火墙：
```
sudo ufw status
```

缓存连接问题¶

测试 Redis 连接：
```
redis-cli -h localhost -p 6379 ping
```
检查 Redis 日志：
```
sudo journalctl -u redis -f
```

最佳实践¶

生产环境使用 HTTPS
启用缓存以获得更好的性能
定期备份数据库和配置
监控服务器健康和性能
使用环境变量存储密钥
保持软件更新（安全补丁）
使用反向代理（Nginx/Caddy）
设置日志轮转
正确配置防火墙
测试灾难恢复程序