Ứng dụng .NET

Cài .NET 8, 9 hoặc 10 SDK, deploy ASP.NET Core và ứng dụng web C# bằng dotnet publish, cho Kestrel lắng nghe trên $PORT qua ASPNETCORE_URLS và xử lý các lỗi thường gặp.

Cập nhật 09/10/2026 · 7 phút đọc

ZoPanel build ứng dụng web .NET bằng dotnet publish, chạy ứng dụng đã publish như một dịch vụ của tài khoản hosting và đặt nginx kèm SSL phía trước. Dùng cho ASP.NET Core (MVC, Razor Pages, Blazor Server, minimal API) và mọi ứng dụng .NET phục vụ HTTP.

Cài .NET SDK

Quản trị viên cài một lần cho mỗi server:

1. Mở Runtime.
2. Trên thẻ .NET SDK, bấm phiên bản cần cài (.NET 10.0, .NET 9.0 hoặc .NET 8.0). Log tác vụ hiển thị tiến trình cài. Hãy cài mọi phiên bản mà các ứng dụng của bạn nhắm tới: chúng được cài song song.

ZoPanel cung cấp các phiên bản SDK mà Microsoft còn hỗ trợ: .NET 10 (LTS, hỗ trợ đến tháng 11/2028), cùng .NET 9 và .NET 8, cả hai được hỗ trợ đến ngày 10/11/2026. Mỗi gói (dotnet-sdk-10.0, …) đã bao gồm ASP.NET Core runtime tương ứng:

Quan trọng: Microsoft chỉ phát hành gói .NET 8 và .NET 9 cho Debian trên amd64. Trên server Debian arm64, thẻ chỉ cho cài .NET 10 và giải thích lý do; với ứng dụng nhắm net8.0 hoặc net9.0 trên server đó, hãy chuyển sang net10.0, dùng server Ubuntu, hoặc build và chạy ứng dụng dưới dạng container (xem Deploy bằng Docker). Nếu kho của Microsoft chưa có cấu hình cho bản Debian đang dùng, việc cài dừng với thông báo ".NET is not available for Debian … yet: … (deploy with a Dockerfile instead)".

SDK nào build ứng dụng

Ô Phiên bản của ứng dụng chọn SDK. Tự nhận diện đặt ô này theo <TargetFramework> của project (net9.0 → 9.0; với <TargetFrameworks>, lấy bản mới nhất). Khi build, ZoPanel thêm vào bản phát hành một file global.json cố định phiên bản SDK đó, nên log build ghi "Using the .NET 9.0 SDK". Nếu repository đã có global.json riêng (trong thư mục project hoặc thư mục cha), file đó quyết định và ZoPanel không thêm file nữa. Khi không có phiên bản, dùng SDK mới nhất đã cài.

Nếu SDK của phiên bản đó chưa được cài, deploy dừng với thông báo "the .NET 9.0 SDK is not installed (installed: …)". Hãy cài nó ở mục Runtime, hoặc đổi target framework của project.

ZoPanel nhận diện gì

Dự án được coi là .NET khi thư mục gốc có file .csproj, file .sln, hoặc có .csproj nằm sâu một cấp thư mục. Sau đó ZoPanel tìm project sâu tối đa hai cấp (ví dụ src/MyApp/MyApp.csproj), bỏ qua bin, obj và thư mục ẩn:

• Ưu tiên project web (Microsoft.NET.Sdk.Web), gắn nhãn ASP.NET Core. Nếu không có, dùng project đầu tiên có Microsoft.NET.Sdk, gắn nhãn .NET.
• Khi có nhiều project, log build ghi rõ project nào được publish.

Với project MyApp.csproj, các lệnh đề xuất là:

Việc nhận diện chạy theo thứ tự cố định: package.json, composer.json, Gemfile hoặc file build Java trong cùng thư mục được xét trước .NET. Nếu framework bị nhận sai, đặt Thư mục gốc là thư mục project, hoặc tắt Tự nhận diện và tự đặt lệnh. Procfile có dòng web: sẽ thay lệnh chạy.

Deploy ứng dụng .NET

1. Ở Website → Thêm website, chọn Git deploy, nhập tên miền và repository. Xem Git deploy.
2. Mở tab Deploy của website, kiểm tra Framework và các lệnh trong Build & chạy.
3. Muốn sửa lệnh, tắt Tự nhận diện, sửa lệnh rồi bấm Lưu & deploy lại.
4. Thêm cấu hình trong Biến môi trường.
5. Bấm Deploy ngay.

Bản mới chỉ được đưa lên khi trả lời Đường dẫn health check (mặc định /) với mã dưới 500 trong vòng 90 giây. Trong lúc đó bản cũ vẫn chạy. Muốn build bằng SDK khác, tắt Tự nhận diện và chọn Phiên bản (xem SDK nào build ứng dụng).

Muốn deploy không qua Git, tạo website kiểu Node / Proxy, tải mã nguồn lên domains/<tên-miền>/source và chọn nguồn File đã tải lên (Quản lý file). Hãy tải mã nguồn chứ không phải thư mục publish: ZoPanel tự chạy restore và publish.

Cổng và URL

Kestrel phải lắng nghe tại 127.0.0.1, trên cổng trong biến PORT. Lệnh chạy đề xuất làm việc này bằng ASPNETCORE_URLS=http://127.0.0.1:$PORT. Giữ nguyên tiền tố đó khi sửa lệnh, và không ghi cứng URL ở nơi khác:

• Bỏ các lời gọi UseUrls(...) và mục Kestrel:Endpoints trong appsettings.json: chúng ghi đè ASPNETCORE_URLS.
• Không thêm endpoint HTTPS cho Kestrel. nginx lo SSL và nói chuyện với ứng dụng qua HTTP thường.

PORT khác nhau giữa hai slot blue/green (slot thứ hai dùng cổng gốc cộng 10000), nên đừng ghi số cổng vào cấu hình.

Phía sau nginx

nginx gửi kèm X-Forwarded-For và X-Forwarded-Proto. Để ứng dụng thấy IP thật của khách và giao thức https (cho redirect, cookie, callback OAuth), bật middleware forwarded headers ở đầu Program.cs:

using Microsoft.AspNetCore.HttpOverrides;

var app = builder.Build();
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});

Proxy nằm ở 127.0.0.1, địa chỉ mà ASP.NET Core mặc định tin cậy.

Tên assembly

Lệnh chạy giả định file DLL được publish trùng tên file project. Nếu project khai báo <AssemblyName>, sửa lệnh chạy thành out/<AssemblyName>.dll.

Biến môi trường

Các biến trong Biến môi trường dùng được khi build và khi chạy. ZoPanel đặt thêm PORT và HOST=127.0.0.1.

• Tên biến gồm chữ, số và _, bắt đầu bằng chữ hoặc _, tối đa 64 ký tự. Giá trị nằm trên một dòng, tối đa 8.192 ký tự. Tối đa 200 biến.
• Giá trị được lưu trong file chỉ root đọc được và được systemd truyền vào, không bao giờ nằm trên dòng lệnh.

ASP.NET Core đọc biến môi trường như cấu hình. Dùng hai dấu gạch dưới cho khoá lồng nhau:

Với database MariaDB hoặc PostgreSQL tạo trong ZoPanel, dùng server 127.0.0.1. Xem Database.

Bộ nhớ

Ứng dụng, quá trình build và mọi thứ khác của tài khoản dùng chung RAM (MB) của gói. Tiến trình vượt giới hạn bị kernel dừng và ZoPanel khởi động lại ứng dụng. Khi deploy, quá trình build và khoảng thời gian ngắn bản cũ và bản mới chạy song song cùng cần bộ nhớ.

Project ASP.NET Core mặc định dùng server garbage collection, giữ nhiều bộ nhớ hơn theo số nhân CPU. Với gói nhỏ, chuyển sang workstation GC hoặc giới hạn heap bằng biến môi trường (giá trị heap viết ở dạng hexa):

DOTNET_gcServer=0
DOTNET_GCHeapHardLimit=0x20000000

0x20000000 là 512 MiB. Xem Gói hosting và giới hạn.

File và log

• Ứng dụng chỉ ghi được trong thư mục home của tài khoản và thư mục /tmp riêng. Lưu file upload trong Đường dẫn lưu trữ cố định (ví dụ wwwroot/uploads) hoặc trong database: mỗi bản release là một thư mục mới, 5 bản gần nhất được giữ để Rollback.
• Log ứng dụng trong tab Deploy hiển thị 400 dòng output console mới nhất. Bật Trực tiếp để theo dõi liên tục.
• Output restore và publish của từng lần deploy nằm trong Tác vụ. Log nginx ở tab Nhật ký.

Xử lý sự cố

Xem thêm

• Ứng dụng Node.js và Python: quy trình deploy, cổng và phát hành blue/green
• Git deploy
• Deploy bằng Docker
• Gói hosting và giới hạn
• Host ASP.NET Core trên Linux với Nginx (Microsoft)
• Cấu hình ASP.NET Core với proxy (Microsoft)