在Linux服务器部署ASP.NET Core应用,如何配置服务并验证访问?

发布人:A5数据发布时间:2026-10-14 13:15阅读量:105

在 Ubuntu 22.04/24.04 LTS 上部署 ASP.NET Core 应用,通常采用“ASP.NET Core 运行时 + systemd + Nginx”的组合:应用由 systemd 负责启动、重启和开机自启,Kestrel 仅监听本机端口,Nginx 对外提供 HTTP/HTTPS 访问并转发请求。这样既能明确服务边界,也便于分层验证和回滚。

导语配图

下面以目标框架为 .NET 8、应用程序集名称为 MyApp.dll、域名为 example.com、内部端口为 5000 的示例展开。命令主要适用于 Ubuntu 22.04/24.04;如果服务器是 Debian、CentOS、AlmaLinux 或其他发行版,应替换软件包安装和防火墙命令。文中的终端输出均为判断成功或失败的示例,不代表实际执行记录。

A5数据为 ASP.NET Core 网站、业务后台和接口服务提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地的物理服务器资源,涵盖常规 Xeon 与 AMD EPYC 平台,并提供 SSD、NVMe 等存储及不同网络线路配置。多地区部署与 CPU、内存和存储资源组合,可承载应用进程、数据库及配套业务服务,满足从常规建站到多任务运行的资源需求。

一、准备条件与部署结构

1. 明确环境和上线目标

本次部署需要确认以下信息:

  • 操作系统:Ubuntu 22.04 或 Ubuntu 24.04 LTS。
  • 应用运行时:示例使用 ASP.NET Core Runtime 8.0。
  • 发布方式:采用依赖框架部署,服务器安装对应 ASP.NET Core Runtime。
  • 应用文件:发布目录中至少包含 MyApp.dll、MyApp.deps.json、MyApp.runtimeconfig.json 及应用依赖文件。
  • 进程管理:systemd,服务名为 myapp.service。
  • 反向代理:Nginx。
  • 应用内部监听地址:127.0.0.1:5000。
  • 对外访问端口:HTTP 使用 80,HTTPS 使用 443。
  • 运行账户:不使用 root,创建专用账户 appsvc。

建议采用如下目录结构:

/srv/aspnet/myapp/
├── current -> /srv/aspnet/myapp/releases/20250101093000
└── releases/
    ├── 20250101093000/
    └── 20250102114500/

current 是当前生效版本的软链接,systemd 始终从该路径启动应用。发布新版本时只切换软链接,不直接覆盖旧版本,便于回滚。

一、准备条件与部署结构 / 1. 明确环境和上线目标配图

2. 检查服务器架构和系统版本

先登录服务器,确认发行版、架构、磁盘和内存情况:

cat /etc/os-release
uname -m
df -h /
free -h

常见架构对应关系如下:

uname -m 输出.NET 发布运行时标识
x86_64linux-x64
aarch64linux-arm64

示例中如果显示:

ID=ubuntu
VERSION_ID="22.04"
x86_64

则可以使用 Ubuntu 22.04 的软件源,并在构建时选择 linux-x64。如果服务器是 ARM 架构,发布包和依赖也应与 linux-arm64 匹配。

3. 备份现有配置

如果服务器已经运行旧版本,先记录当前服务和 Nginx 配置。首次部署可以跳过不存在的文件:

sudo systemctl status myapp.service --no-pager || true
sudo cp -a /etc/systemd/system/myapp.service \
  /etc/systemd/system/myapp.service.bak 2>/dev/null || true
sudo cp -a /etc/nginx/sites-available/myapp \
  /etc/nginx/sites-available/myapp.bak 2>/dev/null || true
readlink -f /srv/aspnet/myapp/current 2>/dev/null || true

不要在未确认目录内容的情况下使用 rm -rf 清理发布目录。生产环境应至少保留当前版本和上一个可用版本。

二、准备 ASP.NET Core 发布包和运行时

1. 在开发机或构建机发布应用

如果项目目标框架为 net8.0,可以在项目目录执行:

dotnet publish ./MyApp.csproj \
  -c Release \
  -r linux-x64 \
  --self-contained false \
  -o ./publish

参数含义:

  • -c Release:使用 Release 配置发布。
  • -r linux-x64:面向 x86_64 Linux。如果服务器是 ARM,替换为 linux-arm64。
  • --self-contained false:不把 .NET 运行时打入应用包,服务器必须安装匹配的 ASP.NET Core Runtime。
  • -o ./publish:将发布结果输出到 publish 目录。

发布完成后检查主程序集:

test -f ./publish/MyApp.dll && echo "publish package: OK"
find ./publish -maxdepth 1 -type f -printf '%f\n' | sort | head -20

如果应用包含原生依赖,不能只根据服务器 CPU 架构判断兼容性,还要确认发布时使用的 RID 和依赖库。无法确认时,可以在目标服务器上使用 dotnet --info、ldd 等命令进一步检查。

如果不希望服务器安装 .NET Runtime,也可以发布为自包含模式:

dotnet publish ./MyApp.csproj \
  -c Release \
  -r linux-x64 \
  --self-contained true \
  -o ./publish

自包含发布包体积通常更大,启动命令也不再是 dotnet MyApp.dll,而是直接执行发布目录中的应用文件。本文后续按依赖框架部署方式配置。

2. 将发布包传到服务器

可以通过 rsync 将发布内容传到服务器临时目录:

rsync -av ./publish/ deploy@example-server:/tmp/myapp-release/

目标目录 /tmp/myapp-release/ 应专门用于本次发布,避免使用包含其他文件的目录。传输完成后,在服务器上检查:

find /tmp/myapp-release -maxdepth 1 -type f -printf '%f\n' | sort
test -f /tmp/myapp-release/MyApp.dll && echo "package received: OK"

如果发布包通过压缩文件传输,解压前应确认临时目录内容,避免覆盖系统目录或旧版本目录:

sudo install -d -m 0750 /tmp/myapp-release
sudo tar -xzf /tmp/myapp-release.tar.gz -C /tmp/myapp-release

3. 安装匹配的 ASP.NET Core Runtime

先确认系统版本和现有运行时:

source /etc/os-release
printf 'Ubuntu version: %s\n' "$VERSION_ID"
dotnet --info 2>/dev/null || true
dotnet --list-runtimes 2>/dev/null || true

以 Ubuntu 22.04 或 24.04、ASP.NET Core Runtime 8.0 为例:

sudo apt-get update
sudo apt-get install -y wget ca-certificates

source /etc/os-release
wget "https://packages.microsoft.com/config/ubuntu/${VERSION_ID}/packages-microsoft-prod.deb" \
  -O /tmp/packages-microsoft-prod.deb

sudo dpkg -i /tmp/packages-microsoft-prod.deb
rm -f /tmp/packages-microsoft-prod.deb

sudo apt-get update
sudo apt-get install -y aspnetcore-runtime-8.0

验证运行时:

dotnet --list-runtimes | grep -E 'Microsoft\.(AspNetCore|NETCore)\.App'

正常情况下可以看到类似结果:

Microsoft.AspNetCore.App 8.0.x [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 8.0.x [/usr/share/dotnet/shared/Microsoft.NETCore.App]

版本必须和应用的目标框架相容。如果 MyApp.runtimeconfig.json 显示的是 net7.0 或其他版本,应安装对应的 ASP.NET Core Runtime,不能只因为服务器已经安装了某个版本就直接启动。

三、创建运行账户并部署应用

1. 创建专用账户和目录

应用进程不建议使用 root 运行。执行以下命令创建系统组、系统用户和发布目录:

if ! getent group appsvc >/dev/null; then
  sudo groupadd --system appsvc
fi

if ! id appsvc >/dev/null 2>&1; then
  sudo useradd \
    --system \
    --gid appsvc \
    --home-dir /nonexistent \
    --shell /usr/sbin/nologin \
    appsvc
fi

sudo install -d -o appsvc -g appsvc -m 0750 \
  /srv/aspnet/myapp/releases

sudo install -d -o root -g appsvc -m 0750 \
  /etc/myapp

检查账户和目录:

id appsvc
ls -ld /srv/aspnet/myapp /srv/aspnet/myapp/releases /etc/myapp

appsvc 不需要交互式登录权限。应用如果需要写入上传文件、缓存或临时数据,应单独创建可写目录,而不是给整个应用目录开放写权限。

2. 创建新版本目录并切换当前版本

在服务器上执行:

RELEASE="$(date +%Y%m%d%H%M%S)"
TARGET="/srv/aspnet/myapp/releases/$RELEASE"

sudo install -d -o appsvc -g appsvc -m 0750 "$TARGET"
sudo cp -a /tmp/myapp-release/. "$TARGET/"
sudo chown -R appsvc:appsvc "$TARGET"

if [ -e /srv/aspnet/myapp/current ] && \
   [ ! -L /srv/aspnet/myapp/current ]; then
  echo "current exists but is not a symbolic link; stop deployment"
  exit 1
fi

sudo ln -sfn "$TARGET" /srv/aspnet/myapp/current

检查软链接和主程序集:

readlink -f /srv/aspnet/myapp/current
sudo -u appsvc test -r /srv/aspnet/myapp/current/MyApp.dll
echo $?

最后一条命令返回 0,表示运行账户至少可以读取主程序集。若返回非零,应检查目录权限:

namei -l /srv/aspnet/myapp/current/MyApp.dll

不要直接使用 chmod -R 777 处理权限问题。应沿着路径检查每一级目录的执行权限、文件属主和应用实际需要的写入位置。

四、配置 systemd 管理 ASP.NET Core 服务

1. 创建服务单元文件

创建 /etc/systemd/system/myapp.service:

sudo tee /etc/systemd/system/myapp.service > /dev/null <<'EOF'
[Unit]
Description=ASP.NET Core MyApp
After=network-online.target
Wants=network-online.target

[Service]
Type=exec
User=appsvc
Group=appsvc
WorkingDirectory=/srv/aspnet/myapp/current
ExecStart=/usr/bin/dotnet /srv/aspnet/myapp/current/MyApp.dll

Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://127.0.0.1:5000

Restart=on-failure
RestartSec=5
KillSignal=SIGINT
SyslogIdentifier=myapp

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target
EOF

这里将 Kestrel 绑定到 127.0.0.1:5000,外部用户不能直接访问该端口,只能通过 Nginx 转发。如果应用代码显式调用了 ConfigureKestrel 或 Listen,需要确认代码中的监听配置没有覆盖 ASPNETCORE_URLS。

应用配置中的环境变量可以使用双下划线映射层级配置,例如:

ConnectionStrings__Default=Server=127.0.0.1;Port=3306;Database=mydb

数据库密码等敏感信息不要提交到公开仓库,也不要写入 Nginx 配置。可以通过 systemd 的 EnvironmentFile、密钥管理服务或受限权限的配置文件注入。

2. 加载并启动服务

先检查服务文件语法和内容:

sudo systemd-analyze verify /etc/systemd/system/myapp.service
sudo systemctl cat myapp.service

如果没有错误,再加载、启动并设置开机自启:

sudo systemctl daemon-reload
sudo systemctl enable --now myapp.service

验证服务状态:

systemctl is-enabled myapp.service
systemctl is-active myapp.service
sudo systemctl status myapp.service --no-pager -l

预期状态类似:

enabled
active

确认应用只监听本机端口:

sudo ss -lntp | grep ':5000'

示例结果:

LISTEN 0 512 127.0.0.1:5000 0.0.0.0:* users:(("dotnet",pid=1234,fd=123))

如果应用反复退出,先查看日志,不要立即修改多个配置:

sudo journalctl -u myapp.service -n 80 --no-pager
sudo journalctl -u myapp.service -f

3. 验证应用本地响应

在服务器本机访问 Kestrel:

curl -i --max-time 5 http://127.0.0.1:5000/

如果应用有明确的健康检查接口,例如 /healthz,优先使用:

curl -i --max-time 5 http://127.0.0.1:5000/healthz

成功通常表现为 200 OK,也可能是应用设计的 204 No Content 或合法的 3xx 跳转。根路径返回 404 Not Found 并不必然表示服务失败,可能只是应用没有配置 / 路由;此时应改用实际存在的接口验证。

五、配置 Nginx 反向代理

1. 安装并准备 Nginx

sudo apt-get update
sudo apt-get install -y nginx
sudo systemctl enable --now nginx

创建站点配置:

sudo tee /etc/nginx/sites-available/myapp > /dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;

    server_name example.com www.example.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:5000;
        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-Proto $scheme;

        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}
EOF

将 example.com 和 www.example.com 替换为实际域名。如果暂时通过服务器 IP 访问,可以将其改为:

server_name _;

启用站点:

sudo ln -sfn /etc/nginx/sites-available/myapp \
  /etc/nginx/sites-enabled/myapp

如果访问时仍显示 Nginx 默认欢迎页,说明默认站点优先匹配。确认该服务器没有其他业务依赖默认站点后,可以先备份再禁用:

sudo cp -a /etc/nginx/sites-available/default \
  /etc/nginx/sites-available/default.bak

sudo unlink /etc/nginx/sites-enabled/default

2. 检查并加载 Nginx 配置

任何 reload 或 restart 前都应先执行语法检查:

sudo nginx -t

成功示例:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

确认无误后平滑加载:

sudo systemctl reload nginx
systemctl is-active nginx

reload 通常不会中断已有连接;如果配置无法加载,Nginx 会拒绝执行 reload。此时应根据错误提示检查括号、分号、路径和重复配置,不要直接覆盖整个 /etc/nginx/nginx.conf。

3. 配置防火墙和云平台安全组

如果服务器使用 UFW,先确认当前状态:

sudo ufw status verbose

远程操作服务器时,必须先放行实际使用的 SSH 端口,再考虑启用 UFW。例如 SSH 使用默认 22 端口:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

确认规则无误后再启用:

sudo ufw enable
sudo ufw status numbered

如果 SSH 使用其他端口,应将 22/tcp 换成实际端口。错误启用防火墙可能导致当前远程连接中断。云服务器还需要检查云平台安全组或网络 ACL,至少放行:

  • SSH 管理端口,仅对必要来源开放。
  • TCP 80,用于 HTTP 访问或证书验证。
  • TCP 443,用于 HTTPS 访问。

不要为了让外部用户直接访问而放行 TCP 5000。该端口应继续保持本机监听。

六、分层验证访问链路

部署完成后,应从应用进程、Nginx、本机回环、域名解析、外部网络五个层面验证。

六、分层验证访问链路配图

1. 验证服务和监听端口

systemctl is-active myapp.service
systemctl is-active nginx
sudo ss -lntp | grep -E ':(5000|80|443)\b'

预期关系是:

  • dotnet 监听 127.0.0.1:5000。
  • nginx 监听 0.0.0.0:80 或 [::]:80。
  • 配置 HTTPS 后,Nginx 还应监听 443。

如果 5000 没有监听,优先检查 systemd 日志;如果 5000 正常而 80 没有监听,检查 Nginx 状态和配置测试结果。

2. 验证 Nginx 到应用的转发

域名尚未解析时,可以使用 Host 请求头在服务器本机验证:

curl -i --max-time 5 \
  -H 'Host: example.com' \
  http://127.0.0.1/

如果使用 server_name _;,可以直接执行:

curl -i --max-time 5 http://127.0.0.1/

此时返回的响应应来自 ASP.NET Core 应用,而不是 Nginx 默认页。可以在应用响应头、健康接口或访问日志中进一步判断。

查看 Nginx 错误日志:

sudo tail -n 50 /var/log/nginx/error.log

查看访问日志:

sudo tail -n 50 /var/log/nginx/access.log

3. 验证域名和外部访问

先在服务器或管理机上检查域名解析:

getent hosts example.com

解析结果应指向服务器公网 IP。然后从服务器外部网络执行:

curl -I --max-time 10 http://example.com/

如果返回 200、204 或符合应用设计的 3xx,说明基本访问链路已经建立。若返回 502 Bad Gateway,表示 Nginx 已经收到请求,但无法正常连接或读取后端应用,应回到 127.0.0.1:5000 的本地验证。

七、常见异常和处理方式

1. 提示找不到兼容的框架版本

典型日志可能包含:

It was not possible to find any compatible framework version

处理顺序如下:

dotnet --list-runtimes
cat /srv/aspnet/myapp/current/MyApp.runtimeconfig.json

对比应用要求的 Microsoft.AspNetCore.App 版本和服务器实际安装版本。解决方式通常是:

  • 安装应用需要的 ASP.NET Core Runtime。
  • 重新发布为服务器已有的目标框架。
  • 确认发布包没有混入其他项目的 runtimeconfig.json。

2. systemd 返回 217/USER 或 203/EXEC

217/USER 通常表示 User=appsvc 或 Group=appsvc 不存在,检查:

getent passwd appsvc
getent group appsvc

203/EXEC 通常与启动路径、执行文件或运行时路径有关,检查:

command -v dotnet
ls -l /usr/bin/dotnet
ls -l /srv/aspnet/myapp/current/MyApp.dll
sudo systemctl cat myapp.service

如果使用的是自包含发布,不能继续使用 dotnet MyApp.dll 的启动方式,应改为发布目录中的实际可执行文件,并为其设置执行权限。

3. Nginx 返回 502

按以下顺序判断:

七、常见异常和处理方式 / 3. Nginx 返回 502配图

curl -i http://127.0.0.1:5000/
sudo ss -lntp | grep ':5000'
sudo tail -n 50 /var/log/nginx/error.log
  • 本机访问也失败:问题在 ASP.NET Core 服务、运行时、配置或端口。
  • 本机访问成功,Nginx 返回 502:检查 proxy_pass 地址、端口和 Nginx 配置。
  • Nginx 错误日志显示 connect() failed (111: Connection refused:后端没有监听,或监听地址和代理地址不一致。
  • 日志显示超时:检查应用启动耗时、数据库连接、上游依赖和 proxy_read_timeout。

4. 返回 500 或应用启动后立即退出

先看应用日志:

sudo journalctl -u myapp.service -n 120 --no-pager

常见原因包括:

  • Production 环境缺少必要配置。
  • 数据库、缓存或消息服务地址错误。
  • appsvc 无法读取配置或证书文件。
  • 应用启动时执行数据库连接检查,但网络或凭据不可用。
  • 应用尝试写入只读的发布目录。

如果确实需要写文件,可以创建独立目录:

sudo install -d -o appsvc -g appsvc -m 0750 /var/lib/myapp

然后在应用配置中将上传、缓存或临时文件路径指向 /var/lib/myapp,不要把整个 /srv/aspnet/myapp 改成所有用户可写。

5. 页面显示 Nginx 默认页或域名访问错误站点

检查有效配置:

sudo nginx -T | grep -n -A8 -B3 'server_name'

重点确认:

  • server_name 是否写成实际域名。
  • 是否仍启用了默认站点。
  • DNS 是否指向当前服务器。
  • 请求是否命中了另一个监听 80 端口的 server 块。

修改后必须执行:

sudo nginx -t && sudo systemctl reload nginx

6. 应用生成错误的 HTTP/HTTPS 跳转

Nginx 将客户端协议通过 X-Forwarded-Proto 传给后端,但 ASP.NET Core 应用还需要正确启用转发头处理。若应用强制 HTTPS、生成绝对 URL 或使用安全 Cookie,应在应用管线中正确配置 Forwarded Headers,并确保该中间件处于认证、重定向等逻辑之前。不要简单删除 HTTPS 重定向来掩盖代理配置问题。

完成 HTTP 链路验证后,再在 Nginx 配置 443、证书和 HTTP 到 HTTPS 的跳转。证书文件路径、续期方式和私钥权限应单独管理,应用本身仍可以继续监听本机的 HTTP 端口。

八、上线验收与回滚检查项

1. 验收清单

可以按以下顺序记录验收结果:

  • [ ] dotnet --list-runtimes 包含应用所需的 ASP.NET Core Runtime。
  • [ ] /srv/aspnet/myapp/current 是指向有效发布目录的软链接。
  • [ ] appsvc 可以读取 MyApp.dll,应用没有使用 root 运行。
  • [ ] systemctl is-active myapp.service 返回 active。
  • [ ] systemctl is-enabled myapp.service 返回 enabled。
  • [ ] 应用监听 127.0.0.1:5000,没有直接暴露内部端口。
  • [ ] curl http://127.0.0.1:5000/ 或健康检查接口返回预期结果。
  • [ ] nginx -t 检查成功,Nginx 服务处于 active 状态。
  • [ ] 通过本机 Host 头访问 Nginx 时能够得到应用响应。
  • [ ] 域名解析指向正确公网 IP。
  • [ ] 外部网络访问 80 或 443 返回预期状态。
  • [ ] 云安全组和服务器防火墙没有误放行 5000,也没有阻断必要的 80、443。
  • [ ] 已保存当前版本路径、systemd 配置、Nginx 配置和关键日志。

2. 应用版本回滚

发布新版本前,先记录旧版本:

readlink -f /srv/aspnet/myapp/current

例如旧版本为:

/srv/aspnet/myapp/releases/20250101093000

新版本启动失败或验证不通过时,将 current 切回旧目录:

OLD="/srv/aspnet/myapp/releases/20250101093000"

sudo systemctl stop myapp.service
sudo ln -sfn "$OLD" /srv/aspnet/myapp/current
sudo systemctl start myapp.service

systemctl is-active myapp.service
curl -i --max-time 5 http://127.0.0.1:5000/

确认旧版本恢复后,再通过 Nginx 验证:

curl -i --max-time 5 \
  -H 'Host: example.com' \
  http://127.0.0.1/

回滚期间不要立即删除失败版本。应保留其日志和目录,待确认问题原因后再清理。若新版本包含数据库结构变更,应用文件回滚不等于数据库回滚;上线前应确认数据库迁移是否向后兼容,并在执行不可逆变更前完成数据库备份。

如果问题来自 Nginx 配置,可以恢复备份并重新验证:

sudo cp -a /etc/nginx/sites-available/myapp.bak \
  /etc/nginx/sites-available/myapp

sudo nginx -t && sudo systemctl reload nginx

只有在 systemd 服务、应用本地端口、Nginx 转发和外部访问均验证通过后,才应将新版本标记为当前生产版本。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3639.html

相关推荐