在香港服务器部署Nuxt网站,如何配置SSR运行与反向代理?
香港服务器上部署 Nuxt 生产站点时,推荐将 Nuxt 的服务端渲染进程仅绑定在 127.0.0.1,由 Nginx 对外提供 HTTP/HTTPS 入口,再使用 systemd 负责进程拉起、自动重启和日志收集。这样可以避免 Node 端口直接暴露,同时把证书、访问日志、超时策略和资源限制集中在网关与服务管理层处理。
以下示例以 Ubuntu 22.04/24.04、Nuxt 3、Node.js 20 LTS、Nginx 和单台香港服务器为基础。示例域名使用 example.com,应用端口使用 3000,实际操作时需要替换为自己的域名、目录、端口和环境变量。文中的终端输出属于判断成功与否的示例,不代表某台实际服务器的执行记录。
一、部署架构与准备条件
1. 推荐的生产链路
部署完成后的请求路径如下:

浏览器
│
├─ HTTPS :443
└─ HTTP :80
│
▼
Nginx
│ 反向代理
▼
127.0.0.1:3000
│
▼
Nuxt .output/server/index.mjs
各组件的职责应保持清晰:
| 组件 | 主要职责 | 不建议承担的职责 |
|---|---|---|
| DNS | 将域名解析到香港服务器公网 IP | 不负责应用健康检查 |
| Nginx | HTTPS、请求转发、访问日志、超时控制 | 不直接运行 Nuxt 构建产物 |
| systemd | 启动、停止、重启和限制 Nuxt 进程 | 不替代应用自身的错误处理 |
| Nuxt/Nitro | 路由、服务端渲染、接口和页面响应 | 不直接暴露公网监听端口 |
| 备份机制 | 保存代码、环境配置和持久化数据 | 不等同于一次临时压缩 |
Nuxt 生产运行时应执行构建后的 .output/server/index.mjs,而不是使用开发命令。npm run dev 适合开发调试,不能作为生产进程守护方案;nuxi generate 生成的是静态站点,也不适用于需要服务端渲染的部署目标。
2. 服务器与域名条件
开始前确认以下条件:
- 已有香港服务器公网 IPv4 地址;如果启用 IPv6,需要同时确认服务器具有可用 IPv6 地址。
- 域名的
A记录指向服务器 IPv4。 - 只有在 IPv6 已正确配置时,才添加
AAAA记录。 - 服务器系统可以使用
sudo。 - 应用源码包含可用的
package-lock.json、pnpm-lock.yaml或其他固定依赖锁文件。 - Node.js 版本满足当前 Nuxt 项目要求。示例以 Node.js 20 LTS 为准。
- 80 和 443 端口能够从公网访问,22 端口能够用于 SSH 管理。
- 应用需要的数据库、对象存储、外部 API 等依赖已经准备好。
香港服务器本身不需要特殊的 Nuxt 配置。真正需要特别检查的是 DNS 到服务器的方向、IPv4/IPv6 是否一致、香港机房安全组是否放行 80/443,以及应用访问的上游服务是否允许来自该服务器的连接。
A5数据提供香港物理服务器租用,覆盖入门建站、Xeon Gold及AMD EPYC等资源档位,可为Nuxt服务端渲染与Nginx反向代理提供部署基础。其香港产品提供不同容量的内存及SSD、NVMe存储方案,承载页面渲染、接口服务与业务数据读写;不同套餐配有CN2或国际带宽,面向跨境企业网站和业务后台提供相应的计算、存储与网络资源。
3. 检查系统、Node.js 和 Nginx
以下命令适用于 Ubuntu。执行安装前应先确认服务器中是否已经运行其他网站,避免覆盖已有 Nginx 或 Node.js 配置。
sudo apt update
sudo apt install -y nginx nodejs npm rsync curl ca-certificates
检查版本:
node --version
npm --version
nginx -v
示例结果:
v20.11.1
10.2.4
nginx version: nginx/1.24.0
如果 Node.js 版本明显低于项目要求,不要直接继续构建。应先通过已经批准的系统包源或 Node.js 版本管理方案安装合适的 LTS 版本,然后重新验证:
node -p "process.versions.node"
node -p "process.platform + ' ' + process.arch"
systemd 不会自动读取交互式 Shell 中的 Node.js 版本管理环境。如果 Node.js 是通过用户级版本管理工具安装的,必须在 systemd 服务中填写实际的 Node 路径,而不能直接假设 /usr/bin/node 一定存在:
command -v node
readlink -f "$(command -v node)"
4. 检查 DNS 与公网端口
先检查域名解析结果:
dig +short A example.com
dig +short AAAA example.com
没有安装 dig 时,可以使用:
getent ahosts example.com
确认结果中存在服务器实际公网地址。若域名存在错误的 AAAA 记录,而服务器没有可用 IPv6,部分访问者会优先连接 IPv6 并失败。此时应删除错误的 AAAA 记录,或者先正确配置 IPv6。
服务器本机检查监听端口:
sudo ss -lntp
初始状态可能只有 SSH 端口,Nginx 和 Nuxt 尚未监听属于正常情况。
二、设置防火墙、运行用户和目录
1. 放行必要端口
如果使用云平台安全组,应在安全组中放行:
- TCP 22:仅允许管理来源访问更安全。
- TCP 80:用于 HTTP 访问及证书验证。
- TCP 443:用于 HTTPS 访问。
- 不要对公网放行 Nuxt 的 3000 端口。
如果服务器使用 UFW,先检查当前规则:
sudo ufw status verbose
确认 SSH 允许规则已经存在后,再按需配置:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status numbered
如果 UFW 当前处于关闭状态,启用前必须确认 SSH 规则和云安全组都正确,否则可能把自己锁在服务器外。防火墙调整属于高影响操作,建议保留当前 SSH 会话,并准备云厂商控制台或带外终端作为回退通道:
sudo ufw enable
不要执行包含 ufw reset 的命令来“快速修复”规则,除非已经导出当前防火墙配置并明确知道其他网站和管理端口不会受到影响。
2. 创建专用运行用户
不建议使用 root 直接运行 Nuxt。创建没有登录 Shell 的系统用户:
sudo adduser --system --group --home /srv/nuxt-app nuxt
如果该用户已经存在,可先确认:
getent passwd nuxt
id nuxt
建立发布目录和共享目录:
sudo install -d -o nuxt -g nuxt -m 750 /srv/nuxt-app
sudo install -d -o nuxt -g nuxt -m 750 /srv/nuxt-app/releases
sudo install -d -o nuxt -g nuxt -m 750 /srv/nuxt-app/shared
建议每次发布使用独立的 releases 子目录,current 只作为当前版本软链接。这样新版本构建失败时,不会破坏正在运行的版本。
3. 创建运行时环境文件
将非敏感的站点配置和敏感密钥分开管理更稳妥。示例先创建一个统一环境文件:
sudo install -d -o root -g nuxt -m 750 /etc/nuxt-app
sudo tee /etc/nuxt-app/nuxt.env >/dev/null <<'EOF'
NUXT_PUBLIC_SITE_URL=https://example.com
NUXT_API_BASE=https://api.example.com
NUXT_API_SECRET=replace-with-a-long-random-secret
EOF
sudo chown root:nuxt /etc/nuxt-app/nuxt.env
sudo chmod 640 /etc/nuxt-app/nuxt.env
不要把数据库密码、接口密钥、签名密钥写入 NUXT_PUBLIC_ 开头的变量。Nuxt 会将 public 配置暴露给浏览器,任何放在公开配置中的内容都不能视为秘密。
Nuxt 配置可以明确开启服务端渲染,并区分服务端私密配置和客户端公开配置:
export default defineNuxtConfig({
ssr: true,
runtimeConfig: {
apiSecret: process.env.NUXT_API_SECRET,
public: {
siteUrl: process.env.NUXT_PUBLIC_SITE_URL,
apiBase: process.env.NUXT_API_BASE
}
}
})
如果项目已经有自己的 runtimeConfig,应按照项目结构合并,不要直接覆盖原配置。环境变量名称、配置层级和实际代码读取方式必须保持一致。
三、构建 Nuxt 生产版本
1. 准备代码目录
以下示例假设已经将源码上传到服务器的 /tmp/nuxt-src,并且目录中包含 package.json 和锁文件:
ls -la /tmp/nuxt-src
test -f /tmp/nuxt-src/package.json
test -f /tmp/nuxt-src/package-lock.json
示例输出:
-rw-r--r-- 1 root root 1850 package.json
-rw-r--r-- 1 root root 98234 package-lock.json
生产构建最好使用固定锁文件。若只有 package.json 而没有锁文件,依赖版本可能在不同时间发生变化,不建议直接用于正式发布。
创建本次发布目录并复制源码:
RELEASE_ID="$(date +%Y%m%d-%H%M%S)"
RELEASE="/srv/nuxt-app/releases/$RELEASE_ID"
sudo install -d -o nuxt -g nuxt -m 750 "$RELEASE"
sudo rsync -a --delete \
--exclude node_modules \
--exclude .output \
/tmp/nuxt-src/ "$RELEASE/"
sudo chown -R nuxt:nuxt "$RELEASE"
rsync --delete 会删除目标目录中源目录不存在的文件。上例目标是全新的发布目录,风险较低;不要把该命令直接指向 /srv/nuxt-app/current 或其他正在运行的目录。
2. 安装依赖和构建
在构建阶段需要安装开发依赖,因为 Nuxt 的构建工具通常位于 devDependencies。执行:
sudo -u nuxt bash -lc "
cd '$RELEASE' &&
npm ci --include=dev &&
npm run build
"
如果项目使用 pnpm 或 yarn,应改用项目实际的锁文件和包管理器,不要混用:
sudo -u nuxt bash -lc "
cd '$RELEASE' &&
corepack enable &&
pnpm install --frozen-lockfile &&
pnpm build
"
构建成功后,检查关键文件:
test -f "$RELEASE/.output/server/index.mjs"
du -sh "$RELEASE/.output"
预期至少能看到 .output/server/index.mjs。如果该文件不存在,通常表示项目没有完成 Nuxt 服务端构建、执行了静态生成命令,或者构建脚本并不是当前项目的生产脚本。
检查 Node 入口文件语法:
sudo -u nuxt node --check "$RELEASE/.output/server/index.mjs"
3. 检查 Nuxt 的监听配置
运行时要让 Nuxt 只监听本机回环地址。端口和地址可以通过 systemd 注入,应用自身不要写死公网地址。
如果项目有自定义 Nitro 配置,需要检查是否覆盖了主机和端口:
grep -R "NITRO_HOST\|NITRO_PORT\|HOST\|PORT\|ssr" -n \
"$RELEASE/nuxt.config."* \
"$RELEASE/package.json" 2>/dev/null || true
不要在生产服务器上使用 npm run dev 进行最终验证,因为开发服务器的热更新、依赖加载方式和错误处理行为与生产构建不同。
四、使用 systemd 守护 Nuxt 进程
1. 创建服务单元
先确认 Node.js 的实际路径:
NODE_BIN="$(readlink -f "$(command -v node)")"
printf '%s\n' "$NODE_BIN"
如果输出是 /usr/bin/node,可以按下面示例创建服务;如果路径不同,应替换 ExecStart 中的值。
sudo tee /etc/systemd/system/nuxt-app.service >/dev/null <<'EOF'
[Unit]
Description=Nuxt production application
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=nuxt
Group=nuxt
WorkingDirectory=/srv/nuxt-app/current
EnvironmentFile=-/etc/nuxt-app/nuxt.env
Environment=NODE_ENV=production
Environment=NITRO_HOST=127.0.0.1
Environment=NITRO_PORT=3000
ExecStart=/usr/bin/node /srv/nuxt-app/current/.output/server/index.mjs
Restart=on-failure
RestartSec=5
StartLimitIntervalSec=60
StartLimitBurst=5
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
UMask=027
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
如果应用需要写入上传文件、缓存或本地生成内容,应明确指定可写目录,例如 /srv/nuxt-app/shared/uploads,不要为了方便把整个应用目录改成全局可写:
sudo install -d -o nuxt -g nuxt -m 750 /srv/nuxt-app/shared/uploads
2. 切换当前版本并启动
先将刚刚构建成功的版本设置为当前版本:
sudo ln -sfnT "$RELEASE" /srv/nuxt-app/current
readlink -f /srv/nuxt-app/current
预期输出应为本次发布目录,例如:
/srv/nuxt-app/releases/20250118-143000
加载服务并启动:
sudo systemctl daemon-reload
sudo systemctl enable --now nuxt-app
立即检查状态:
sudo systemctl status nuxt-app --no-pager
成功时可以看到类似状态:
Active: active (running)
再确认监听地址:
sudo ss -lntp | grep ':3000'
正确结果应类似:

LISTEN 0 511 127.0.0.1:3000 0.0.0.0:* users:(("node",pid=1234,fd=20))
如果显示为 0.0.0.0:3000,说明应用已经监听所有网卡。此时应先修正 NITRO_HOST 或项目配置,再继续配置公网入口。
3. 在 Nginx 前验证应用
先不经过域名和证书,直接从服务器本机请求:
curl -i --max-time 10 http://127.0.0.1:3000/
正常情况下应返回 200、301 或应用设计允许的其他状态码,并能看到 Nuxt 输出的 HTML。若只返回空内容或进程立即退出,先查看应用日志,不要继续修改 Nginx:
sudo journalctl -u nuxt-app -n 100 --no-pager
如果项目设置了健康检查路由,例如 server/routes/healthz.get.ts:
export default defineEventHandler(() => ({
status: 'ok'
}))
可以使用更稳定的检查方式:
curl -fsS --max-time 5 http://127.0.0.1:3000/healthz
示例响应:
{"status":"ok"}
健康检查路由应避免返回数据库密码、内部地址、环境变量或完整堆栈信息。
五、配置 Nginx 反向代理
1. 创建 HTTP 配置
先备份 Nginx 配置。备份文件需要限制权限,因为其中可能包含站点路径和证书配置:
sudo tar -C /etc \
-czf "/root/nginx-config-$(date +%F-%H%M%S).tar.gz" \
nginx
sudo chmod 600 /root/nginx-config-*.tar.gz
创建站点配置:
sudo tee /etc/nginx/sites-available/nuxt-app >/dev/null <<'EOF'
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
access_log /var/log/nginx/nuxt-app.access.log;
error_log /var/log/nginx/nuxt-app.error.log warn;
client_max_body_size 10m;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $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-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffering on;
}
}
EOF
proxy_pass 使用 http://127.0.0.1:3000 而不是公网地址,确保请求只能从本机进入 Nuxt。X-Forwarded-Proto 用于让应用识别原始请求是 HTTP 还是 HTTPS,避免生成错误的绝对链接或出现 HTTPS 重定向循环。
如果应用确实使用 WebSocket 或长连接,需要在 Nginx 的 http 级别增加 Upgrade 映射,再在站点中设置对应请求头。普通 Nuxt 页面渲染不需要为了“可能用到”而增加复杂配置。
2. 启用站点并验证配置
创建软链接:
sudo ln -sfn /etc/nginx/sites-available/nuxt-app \
/etc/nginx/sites-enabled/nuxt-app
检查配置语法:
sudo nginx -t
预期结果:
syntax is ok
test is successful
只有在 nginx -t 成功后才重新加载:
sudo systemctl reload nginx
从服务器本机通过域名请求:
curl -i --resolve example.com:80:127.0.0.1 \
http://example.com/
如果域名还未指向该服务器,也可以用公网 IP 做初步验证,但 Nginx 的 server_name 匹配和 Host 头可能不同,最终仍应使用真实域名测试。
3. 配置 HTTPS 证书
在域名已经解析到服务器、80 端口可访问后安装证书工具:
sudo apt install -y certbot python3-certbot-nginx
申请证书:
sudo certbot --nginx \
-d example.com \
-d www.example.com
执行过程中通常会询问是否将 HTTP 重定向到 HTTPS。正式站点一般可以选择重定向,但如果应用还有特殊的 HTTP 回调、健康检查或验证路径,应先确认这些请求不会被重定向破坏。
证书配置完成后,重新检查:
sudo nginx -t
sudo systemctl reload nginx
验证 HTTPS:
curl -I --max-time 15 https://example.com/
检查证书有效期和域名:
echo | openssl s_client \
-connect example.com:443 \
-servername example.com 2>/dev/null |
openssl x509 -noout -subject -issuer -dates
验证自动续期模拟流程:
sudo certbot renew --dry-run
证书续期失败时,优先检查 DNS、80/443 端口、IPv6 记录和 Nginx 配置,不要直接删除 /etc/letsencrypt 下的证书目录。证书目录被删除后,可能需要重新申请并重新生成 Nginx 配置。
六、处理日志、备份和资源边界
1. 查看应用与 Nginx 日志
systemd 服务的标准输出和错误输出默认进入 journald:
sudo journalctl -u nuxt-app -f
查看最近 200 行:
sudo journalctl -u nuxt-app -n 200 --no-pager
查看指定时间段:
sudo journalctl -u nuxt-app \
--since "30 minutes ago" \
--no-pager
Nginx 日志:
sudo tail -f /var/log/nginx/nuxt-app.access.log
sudo tail -f /var/log/nginx/nuxt-app.error.log
正常请求通常会在访问日志中出现 200、304 或应用允许的重定向状态。大量 502 表示 Nginx 无法获得上游响应,不能仅通过刷新页面解决。
可以为 journald 设置容量边界:
sudo install -d -m 755 /etc/systemd/journald.conf.d
sudo tee /etc/systemd/journald.conf.d/nuxt-app.conf >/dev/null <<'EOF'
[Journal]
SystemMaxUse=500M
MaxRetentionSec=14day
EOF
sudo systemctl restart systemd-journald
检查当前日志占用:
sudo journalctl --disk-usage
应用日志中不要记录完整 Cookie、Authorization 令牌、密码、身份证件、支付信息或完整请求体。访问日志也应根据业务合规要求决定保留周期。
Ubuntu 通常已经为 /var/log/nginx/*.log 配置 logrotate,可以先用调试模式检查规则:
sudo logrotate -d /etc/logrotate.conf
2. 代码、环境和业务数据备份
Nuxt 的 .output 可以重新构建,但以下内容仍应备份:
- 版本源码或可复现的发布包。
package-lock.json等依赖锁文件。/etc/nuxt-app/nuxt.env。- Nginx 站点配置和证书续期配置。
- 本地上传文件、生成文件和其他持久化目录。
- 数据库及数据库结构变更记录。
创建一个受限权限的本地备份目录:
sudo install -d -m 700 /var/backups/nuxt-app
备份发布目录、共享目录和环境文件:
BACKUP="/var/backups/nuxt-app/nuxt-$(date +%F-%H%M%S).tar.gz"
sudo tar -czf "$BACKUP" \
-C /srv/nuxt-app releases shared \
-C /etc nuxt-app
sudo chmod 600 "$BACKUP"
ls -lh "$BACKUP"
如果备份中包含用户上传文件或密钥,不应只保存在同一台服务器。建议将备份复制到独立存储,并设置保留周期,例如保留若干个日备份和周备份。备份完成不等于可恢复,至少应定期在隔离目录验证压缩包可读,并演练一次应用版本和配置恢复。
数据库迁移需要单独制定回滚方案。不要把不可逆的数据库删除、字段覆盖或数据清理操作塞进普通发布脚本中。
3. 设置合理的内存和 CPU 边界
Node.js 进程除了 JavaScript 堆,还会使用原生内存、连接池、缓存和系统库,因此 --max-old-space-size 不能等于服务器总内存。以下只是常见的起始参考值:
| 服务器内存 | Node 堆起始值 | 服务内存上限参考 | 适用说明 |
|---|---|---|---|
| 1 GB | 384–512 MB | 700–800 MB | 适合低并发、轻量页面 |
| 2 GB | 768–1024 MB | 1400–1700 MB | 适合单站点常规生产负载 |
| 4 GB | 1536–2048 MB | 2800–3400 MB | 适合页面和接口较多的站点 |
例如,2 GB 服务器可以创建 systemd 限制:
sudo install -d -m 755 /etc/systemd/system/nuxt-app.service.d
sudo tee /etc/systemd/system/nuxt-app.service.d/resources.conf >/dev/null <<'EOF'
[Service]
Environment=NODE_OPTIONS=--max-old-space-size=1024
MemoryHigh=1400M
MemoryMax=1700M
CPUQuota=150%
TasksMax=256
EOF
sudo systemctl daemon-reload
sudo systemctl restart nuxt-app
检查限制是否生效:
sudo systemctl show nuxt-app \
-p MemoryHigh \
-p MemoryMax \
-p CPUQuota \
-p TasksMax
如果服务器只有 1 GB 内存,不应直接套用上面的 2 GB 配置。MemoryMax 设置过低会导致进程被 cgroup 终止,设置过高则无法保护系统。调整后观察:
free -h
sudo systemctl status nuxt-app --no-pager
sudo journalctl -u nuxt-app --since "10 minutes ago" --no-pager
出现频繁 OOM 时,应先确认是内存泄漏、页面数据过大、并发过高、构建误在生产机运行,还是限制设置不合理,不要单纯无限提高 Node 堆。
七、逐项验证生产结果
1. 验证服务状态和端口边界
sudo systemctl is-enabled nuxt-app
sudo systemctl is-active nuxt-app
sudo ss -lntp | grep -E ':80|:443|:3000'
期望结果:
- systemd 返回
enabled。 - 服务返回
active。 - Nginx 监听 80/443。
- Node 只监听
127.0.0.1:3000。 - 公网扫描或服务器监听列表中不应出现
0.0.0.0:3000。
2. 验证服务端渲染
从外部或服务器本机请求首页:
curl -fsS --max-time 15 https://example.com/ -o /tmp/home.html
head -c 500 /tmp/home.html
返回内容应包含服务端输出的 HTML 结构,而不是只返回一个空的根节点。可以进一步检查页面中的标题或服务端注入内容:
grep -E '<title>|__NUXT__|data-v-inspector' /tmp/home.html | head
具体标记会随 Nuxt 版本和项目构建方式变化,不应把某一个字符串作为唯一判断依据。更可靠的判断方式是:
- 禁用浏览器 JavaScript 后,页面仍有服务端返回的主要 HTML。
- 使用
curl请求时,能够获得页面标题、首屏文本或服务端生成的数据。 - 页面加载后客户端水合没有明显报错。
- Nginx 日志显示请求已转发到 Nuxt,而不是返回静态占位页。
3. 验证 HTTPS 和反向代理头
curl -I https://example.com/
curl -I http://example.com/
如果设置了 HTTP 到 HTTPS 的重定向,第二条命令应返回 301 或 308,并带有正确的 Location: https://example.com/...。
检查应用生成的绝对链接、回调地址和 Cookie 属性。如果出现把 HTTPS 页面重定向回 HTTP、Cookie 没有 Secure 属性或生成错误域名,重点检查:
- Nginx 是否发送了
X-Forwarded-Proto。 - Nuxt 的站点 URL 是否配置正确。
- 应用是否错误地信任了来自客户端的伪造转发头。
- 业务代码是否写死了 HTTP 地址。
4. 验证重启恢复能力
在确认当前请求正常后,测试一次受控重启:
sudo systemctl restart nuxt-app
sleep 3
sudo systemctl is-active nuxt-app
curl -fsS --max-time 10 https://example.com/healthz
如果没有 /healthz,可以改为请求首页。不要在高峰期反复执行重启测试,也不要使用压力工具对生产站点进行未经授权的高并发测试。
八、常见异常与处理顺序
1. Nginx 返回 502 Bad Gateway
先从外到内检查:

sudo systemctl status nginx --no-pager
sudo systemctl status nuxt-app --no-pager
sudo ss -lntp | grep ':3000'
curl -i --max-time 10 http://127.0.0.1:3000/
sudo tail -n 50 /var/log/nginx/nuxt-app.error.log
sudo journalctl -u nuxt-app -n 100 --no-pager
不同结果代表的方向不同:
- 本机访问
127.0.0.1:3000失败:先处理 Nuxt 进程、入口文件、环境变量或权限。 - 本机访问成功,Nginx 返回 502:检查
proxy_pass地址、Nginx 配置和 SELinux/AppArmor 等系统策略。 - 服务启动后立即退出:查看 Node 堆栈,常见原因是环境变量缺失、依赖不完整、端口冲突或构建产物不完整。
- 监听的是
127.0.0.1:3001:说明端口配置没有统一,应让 systemd 和 Nginx 使用同一个端口。
2. 首页能打开,但服务端内容为空
重点检查 Nuxt 配置和发布命令:
grep -R "ssr:" -n /srv/nuxt-app/current 2>/dev/null | head
grep -n '"build"\|"generate"\|"dev"' /srv/nuxt-app/current/package.json
常见原因包括:
- 项目配置显式关闭了
ssr。 - 发布时执行了静态生成,而不是生产构建。
- 页面数据只在客户端生命周期中获取。
- 服务端接口请求因环境变量或域名错误失败。
- 服务端渲染依赖的外部 API 无法从香港服务器访问。
先用 curl 检查服务端原始 HTML,再检查 Nuxt 日志和外部 API 连通性,不要先修改 Nginx 缓存。
3. 页面重定向循环或生成错误协议
使用以下命令观察响应头:
curl -I -L --max-redirs 5 https://example.com/
如果看到 HTTP 和 HTTPS 之间反复跳转,检查 Nginx 的 X-Forwarded-Proto 和应用的反向代理信任设置。还要检查是否在 Nginx 和 Nuxt 中同时配置了互相冲突的强制跳转规则。
4. 证书申请失败
检查解析和端口:
dig +short A example.com
dig +short AAAA example.com
sudo ss -lntp | grep -E ':80|:443'
sudo nginx -t
常见原因:
- 域名还未解析到当前服务器。
AAAA指向错误的 IPv6 地址。- 云安全组或 UFW 未放行 80。
- Nginx 配置语法错误,无法加载验证路径。
- 域名启用了错误的代理或重定向链路。
证书申请失败时,先修复其中一项,再重新执行申请,不要连续重复提交造成不必要的申请频率限制。
5. 进程频繁被终止或服务器负载升高
检查服务退出状态、内存和内核记录:
sudo systemctl status nuxt-app --no-pager
sudo journalctl -u nuxt-app --since "1 hour ago" --no-pager
free -h
uptime
dmesg -T | grep -i -E 'oom|killed process|out of memory' | tail -n 20
如果确认是内存不足:
- 检查是否把
npm run build放进了常驻服务。 - 降低页面服务端一次性读取的数据量。
- 检查是否存在缓存无上限增长。
- 调整
NODE_OPTIONS和MemoryMax,但要同时给系统和 Nginx 留出空间。 - 对大文件上传、图片处理等任务使用独立服务或异步任务。
如果是 CPU 持续达到限制,先检查接口慢查询、循环计算、日志量和外部 API 超时,不要立即取消 CPUQuota。
九、发布回滚与配置回退
1. Nuxt 版本回滚
回滚前记录当前版本和候选版本:
readlink -f /srv/nuxt-app/current
find /srv/nuxt-app/releases -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort
确认上一个发布目录仍包含 .output/server/index.mjs 后切换软链接:

PREVIOUS="/srv/nuxt-app/releases/20250117-180000"
test -f "$PREVIOUS/.output/server/index.mjs"
sudo ln -sfnT "$PREVIOUS" /srv/nuxt-app/current
sudo systemctl restart nuxt-app
验证回滚结果:
sudo systemctl is-active nuxt-app
curl -fsS --max-time 10 https://example.com/healthz
readlink -f /srv/nuxt-app/current
回滚只替换应用版本,不要同时删除当前版本、清空 shared 目录或删除数据库内容。若新版本执行过不兼容的数据库迁移,应用版本回退可能仍然无法恢复,此类发布必须提前设计向后兼容迁移和数据库备份。
2. Nginx 配置回退
修改 Nginx 后如果验证失败,先恢复站点配置,而不是直接覆盖整个 /etc/nginx:
sudo cp /etc/nginx/sites-available/nuxt-app \
/etc/nginx/sites-available/nuxt-app.failed
sudo cp /etc/nginx/sites-available/nuxt-app.backup \
/etc/nginx/sites-available/nuxt-app
如果没有单独的备份文件,可以从创建的压缩备份中恢复到临时目录,检查后再复制目标文件:
sudo mkdir -p /root/nginx-restore-check
sudo tar -xzf /root/nginx-config-YYYY-MM-DD-HHMMSS.tar.gz \
-C /root/nginx-restore-check
sudo nginx -t
sudo systemctl reload nginx
不要把旧的整个 Nginx 目录直接覆盖到正在运行的系统上,因为期间可能已经增加其他站点、证书续期配置或安全规则。
3. 证书配置回退
证书更新后如果 Nginx 无法加载:
sudo nginx -t
sudo journalctl -u nginx -n 100 --no-pager
先修复配置语法或恢复对应的站点文件,再执行:
sudo nginx -t
sudo systemctl reload nginx
不要为了回退证书而删除证书目录。证书文件、私钥权限和 Certbot 的续期配置应保留,除非已经明确完成了迁移和替代方案。
十、验收与回滚检查项
正式对外发布前,至少完成以下检查:
- [ ]
A记录指向香港服务器正确 IPv4。 - [ ]
AAAA记录存在时,IPv6 路由和 Nginx IPv6 监听均可用。 - [ ] 云安全组和服务器防火墙仅放行必要端口。
- [ ] Node.js、npm、Nuxt 和 Nginx 版本符合项目要求。
- [ ]
.output/server/index.mjs存在且可以由nuxt用户运行。 - [ ] Nuxt 仅监听
127.0.0.1:3000。 - [ ] systemd 服务状态为
active,并设置了开机启动。 - [ ] Nginx
nginx -t通过。 - [ ] HTTP 与 HTTPS 的跳转符合预期。
- [ ] HTTPS 证书域名和有效期正确。
- [ ]
curl获取首页时能够看到服务端生成的 HTML。 - [ ] Nginx 访问日志、错误日志和 Nuxt journald 日志均可查询。
- [ ] 内存、CPU、文件描述符和任务数边界已经设置并验证。
- [ ] 环境文件权限为受限权限,公开配置中没有秘密。
- [ ] 代码、环境文件、Nginx 配置和持久化数据已有备份。
- [ ] 至少保留一个可启动的上一版本发布目录。
- [ ] 已记录当前
current软链接指向的版本。 - [ ] 已验证一次受控重启后的自动恢复。
- [ ] 已明确应用版本、Nginx 配置和数据库变更的回滚顺序。
当新版本构建成功、本机端口验证通过、Nginx 配置检查通过、HTTPS 页面能够返回服务端 HTML,并且旧版本和配置备份均可用时,再将 DNS 流量切换到该香港服务器,能够把发布风险控制在可观察、可恢复的范围内。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3496.html



