在Linux服务器部署ASP.NET Core应用,如何配置服务并验证访问?
在 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 始终从该路径启动应用。发布新版本时只切换软链接,不直接覆盖旧版本,便于回滚。

2. 检查服务器架构和系统版本
先登录服务器,确认发行版、架构、磁盘和内存情况:
cat /etc/os-release
uname -m
df -h /
free -h
常见架构对应关系如下:
uname -m 输出 | .NET 发布运行时标识 |
|---|---|
x86_64 | linux-x64 |
aarch64 | linux-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
按以下顺序判断:

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



