前端容器化部署指南（阿里云轻量服务器）

技术栈：React + Vite · Podman · Nginx · Let’s Encrypt HTTPS
服务器系统：Alibaba Linux
适用场景：前端静态项目 + 独立后端 API，Nginx 反代解决跨域

架构说明

用户浏览器
  ├─ https://xxx.your-domain.cn/          → Nginx 返回 index.html（SPA）
  └─ https://xxx.your-domain.cn/base_api/ → Nginx 反代到后端 API（无跨域）

• 前端静态文件打包进 Nginx 镜像，由 Podman 容器运行
• API 请求由 Nginx 内部转发，无需配置后端 CORS
• HTTPS 证书由 Let’s Encrypt 免费申请，宿主机管理，挂载进容器

一、首次部署

1. 服务器安装 Podman

sudo dnf install -y podman podman-compose
podman --version

2. 本机打包上传项目

在本机 PowerShell 执行（排除 node_modules / dist / .git）：

tar -czf video-snap-web.tar.gz -C d:\CODE `
  --exclude="video-snap-web/node_modules" `
  --exclude="video-snap-web/dist" `
  --exclude="video-snap-web/.git" `
  video-snap-web

scp video-snap-web.tar.gz root@服务器IP:/root/

3. 服务器解压

cd /root
tar -xzf video-snap-web.tar.gz

4. 阿里云控制台开放端口

轻量服务器控制台 → 防火墙 → 添加规则：

5. 配置 DNS 解析

阿里云控制台 → 云解析 DNS → 找到主域名 → 添加记录：

等待 1～10 分钟生效，验证：

nslookup xxx.your-domain.cn

6. 申请 HTTPS 证书

# 安装 certbot
dnf install -y certbot

# 申请证书（域名 DNS 必须已生效）
cd /root/video-snap-web
podman-compose down        # 释放 80 端口给 certbot 使用
certbot certonly --standalone -d xxx.your-domain.cn

证书路径：/etc/letsencrypt/live/xxx.your-domain.cn/

7. 构建并启动容器

cd /root/video-snap-web
podman-compose up -d --build

访问 https://xxx.your-domain.cn 验证是否正常。

8. 设置证书自动续期

Let’s Encrypt 证书 90 天过期，执行以下命令设置每月自动续期：

(crontab -l 2>/dev/null; echo "0 3 1 * * certbot renew --pre-hook \"podman-compose -f /root/video-snap-web/docker-compose.yml down\" --post-hook \"podman-compose -f /root/video-snap-web/docker-compose.yml up -d\" --quiet") | crontab -

验证是否添加成功：

crontab -l

二、日常更新部署

代码有改动后，在本机项目根目录执行一键脚本：

.\deploy.ps1

脚本自动完成：打包 → 上传 → 服务器解压 → 重建容器 → 清理压缩包。

三、常用运维命令

# 查看容器状态
podman-compose ps

# 查看实时日志
podman-compose logs -f

# 进入容器排查问题
podman exec -it video-snap-web_web_1 sh

# 手动重启
podman-compose restart

# 停止 / 启动
podman-compose down
podman-compose up -d

四、镜像拉取失败备用方案

若 podman-compose up --build 时拉取镜像超时，改用本地构建 dist + 服务器只跑 Nginx 的方式：

本机构建：

cd d:\CODE\video-snap-web
pnpm build
scp -r dist root@服务器IP:/root/video-snap-web/
scp nginx.conf root@服务器IP:/root/video-snap-web/

服务器直接跑 Nginx 容器：

podman run -d --name video-snap-web -p 80:80 -p 443:443 --restart=always \
  -v /root/video-snap-web/dist:/usr/share/nginx/html:ro \
  -v /root/video-snap-web/nginx.conf:/etc/nginx/conf.d/default.conf:ro \
  -v /etc/letsencrypt:/etc/letsencrypt:ro \
  docker.m.daocloud.io/library/nginx:alpine

更新时只需重传 dist/ 再重启：

podman restart video-snap-web

五、关键文件说明