Deploy lên SiSuHost bằng khóa API
Tài liệu cho AI agent và CI: đưa bản mới của một website .NET lên máy chủ SiSuHost (VPS Windows), đổi bản không gián đoạn, theo dõi tới khi chạy ổn, quay lại khi lỗi. Không cần trình duyệt, không cần RDP.
- Địa chỉ gốc
https://host.sisunext.vn/api/v1– cùng địa chỉ với trang này (tên miền GUI của SiSuHost)- Xác thực
Authorization: Bearer shk_…- Định dạng
- JSON camelCase, UTF-8; gói tải lên là
multipart/form-data - Lỗi
- HTTP 4xx kèm
{ "detail": "…" }(câu tiếng Việt, đọc được cho người) - Cách chạy
- Mỗi site có hai khe
a/b: bản mới chạy ở khe trống, đạt kiểm sống mới chuyển Proxy sang, hỏng trong thời gian theo dõi thì tự quay lại bản cũ
Xác thực + phạm vi khóa
Khóa API tạo ở GUI SiSuHost → Khóa API (quản trị viên, nhập lại mật khẩu). Khóa chỉ hiện một lần lúc tạo, bắt đầu bằng shk_, có hạn dùng và thu hồi được. Nhật ký thao tác của SiSuHost ghi khóa <tên> cho mọi việc khóa đó làm.
| Phạm vi | Làm được | Dùng cho |
|---|---|---|
| Một site | Mọi đường /sites/{mã}/… của đúng site đó. Site khác, việc cả máy: 403 | Agent deploy một ứng dụng – nên dùng |
| Cả máy | Mọi site + /host, /apps, /tasks, nối kho /sites/{mã}/feed. Đứng thay mật khẩu xác nhận | Người vận hành / công cụ của nhà cung cấp |
SISUHOST_API_KEY. Agent chỉ deploy một ứng dụng thì xin khóa phạm vi một site.Quy trình deploy cho agent
- Kiểm site:
GET /sites/{mã}→200. ĐọcsignedPackagesOnly:truenghĩa là site chỉ nhận gói có tệp chữ ký.release.json– agent không tự ký được, dừng và báo người. - Đóng gói:
dotnet publish -c Release -o out(xem Chuẩn bị gói). - Gửi: thư mục
outqua delta (khuyên dùng – chỉ gửi tệp đổi), hoặc nén zip rồiPOST /sites/{mã}/packages. Kết quả: bản mới sốnumber, trạng tháireceived. - Đổi bản:
POST /sites/{mã}/deployments/{number}/deploy→202. - Dò mỗi 2 giây
GET /sites/{mã}/deployments/{number}tới khistatelàwatchinghoặcsucceeded(đạt) hoặcfailed/quarantined(hỏng). Giới hạn 10 phút. - Hỏng: đọc
error+GET /sites/{mã}/log?lines=300, báo người. Site vẫn chạy bản cũ – không cần tự quay lại. - Kiểm thật (tùy chọn): gọi trang /
/healthcủa ứng dụng qua tên miền của nó.
Chuẩn bị gói
Gói là đầu ra dotnet publish (ứng dụng ASP.NET Core / Kestrel). SiSuHost cấp cổng qua ASPNETCORE_URLS / PORT và đè các điểm Kestrel:Endpoints gói tự khai – ứng dụng không cần biết cổng.
- Có
sisuhost.jsonở gốc gói (khuyên dùng): khai tệp chạy, phiên bản, biến môi trường, đường kiểm sống. - Không có: SiSuHost đọc
web.config(gói publish cho IIS chạy nguyên trạng, "kiểu IIS" –App_Datagiữ lại qua các lần đổi bản). - Thiếu runtime .NET trên máy: SiSuHost tự tải đúng kênh từ Microsoft. Gói self-contained cũng được.
- Dữ liệu ghi được của ứng dụng: thư mục
datacủa site (đường dẫn ở biến môi trườngSISUHOST_DATA) hoặcApp_Dataở kiểu IIS – thư mục bản là chỉ đọc.
{
"site": "shop",
"name": "MyShop",
"version": "1.4.2",
"entry": "MyShop.dll",
"healthPath": "/health",
"env": { "ASPNETCORE_ENVIRONMENT": "Production" }
}Chuỗi kết nối database (site có database do SiSuHost cấp) đặt sẵn trong biến môi trường của site – không ghi vào gói.
API site
Mọi đường dưới đây nhận khóa của chính site đó hoặc khóa cả máy.
Danh sách site khóa này thấy được (khóa site chỉ thấy site của nó).
SiteStatusReport: trạng thái, khe đang chạy, bản đang chạy, chế độ database, có bắt buộc gói ký không.
{
"site": "shop", "status": "running", "slot": "a",
"deployment": { "number": 12, "version": "1.4.1", "state": "succeeded", "error": null,
"createdAt": "2026-11-20T07:57:56", "activatedAt": "2026-11-20T07:58:05", "watchUntil": null, "finished": true },
"operation": null, "databaseMode": "single", "databasePrefix": null,
"signedPackagesOnly": false, "hostVersion": "2026.11.20.1526"
}Gói nguyên khối, multipart/form-data: (tùy chọn) phần tệp *.release.json đứng trước, rồi phần tệp zip. Trả DeploymentReport (state: "received") – chưa chạy.
curl -sS -H "Authorization: Bearer $SISUHOST_API_KEY" \ -F "[email protected]" \ https://host.sisunext.vn/api/v1/sites/shop/packages
202 – đổi sang bản đó (chạy nền). Bản đang chạy hoặc site đang có thao tác khác: 400.
DeploymentReport của một bản – dò cái này sau khi đổi bản.
Việc dài gần nhất (đổi bản, khởi động lại…): kind, status (running / succeeded / failed / interrupted), bước hiện tại. 204 khi chưa có.
rollback quay về bản trước, restart khởi động lại (cả hai chạy nền, 202); start / stop trả 200.
Văn bản đuôi log của ứng dụng (1 – 5000 dòng).
Chỉ cho site đã nối kho phát hành: lên bản mới nhất của kho. 202 + TaskReport – dò /tasks/{id} (cần khóa cả máy) hoặc GET /sites/{mã}.
Đẩy theo phần thay đổi (delta)
Chỉ gửi tệp máy chủ chưa có (so với các bản site đang giữ) – lần đẩy sau thường chỉ vài tệp dll. Mỗi tệp được kiểm SHA-256 khi dựng lại bản. Không dùng được cho site signedPackagesOnly.
Thân: danh sách mọi tệp của bản. Trả các tệp phải gửi.
// yêu cầu – DeltaManifest
{ "name": "MyShop-1.4.2",
"files": [ { "path": "MyShop.dll", "size": 184320, "sha256": "9f2c…(hex chữ thường)" },
{ "path": "wwwroot/app.css", "size": 5120, "sha256": "…" } ] }
// phản hồi – DeltaPlan
{ "missing": [ "MyShop.dll" ], "reusedBytes": 51234567, "totalBytes": 51418887 }multipart/form-data: phần manifest (đúng JSON đã gửi ở plan) đứng trước, rồi phần files = zip chỉ chứa các tệp missing (đường dẫn trong zip = path). Không thiếu tệp nào thì bỏ phần files. Trả DeploymentReport (received).
Đường dẫn dùng dấu /, tương đối trong thư mục publish. Băm là hex chữ thường.
Trạng thái bản (state)
| Giá trị | Nghĩa | Agent làm gì |
|---|---|---|
received | Đã nhận + kiểm gói, chưa chạy | Gọi …/deploy |
starting | Đang chạy ở khe mới, chờ kiểm sống | Dò tiếp |
watching | Đang phục vụ, còn trong thời gian theo dõi (hỏng thì tự quay lại) | Coi là đạt |
succeeded | Đang phục vụ, đã qua thời gian theo dõi | Xong |
failed | Không lên được – site vẫn chạy bản cũ | Đọc error + log, báo người |
quarantined | Hỏng trong thời gian theo dõi, đã tự quay lại bản cũ, bản bị cách ly | Đọc log, báo người |
retired | Đã bị bản khác thay | – |
API cả máy (chỉ khóa phạm vi cả máy)
Việc dài trả 202 + TaskReport; dò GET /tasks/{id} tới khi status khác running. Việc giữ trong bộ nhớ của SiSuHost tới khi nó khởi động lại.
Bản SiSuHost / Proxy đang chạy, kho phát hành mặc định, bản mới trên kho, lần nâng cấp gần nhất.
Thân { "replaceProxy": true }. Tải bản SiSuHost mới nhất của kho (kiểm chữ ký) rồi nâng cấp; Agent khởi động lại – dò GET /host tới khi version đổi và lastUpgrade.finishedAt có giá trị.
Thêm ứng dụng từ kho phát hành (tạo site, database theo mặc định của kho, ghim khóa, chạy bản đầu). Hỏng giữa chừng thì site vừa tạo được gỡ.
{ "product": "sisuqr", "site": "qr", "domain": "qr.example.vn" }
// kết quả trong TaskReport.app: { "site": "qr", "version": "…", "openUrl": "…", "secret": "…" }Nối site có sẵn với một sản phẩm của kho: { "product": "sisupanel", "notify": true }. Ghim khóa nhà cung cấp + sản phẩm – từ đó site chỉ nhận gói ký đúng sản phẩm đó. DELETE bỏ nối (khóa ghim giữ nguyên).
{ "id": "3f9a1c2b7d10", "kind": "app-install", "target": "qr", "status": "running",
"step": "Tải SiSuQr 2026.11.20.1433 + kiểm chữ ký", "error": null, "version": null, "app": null,
"startedAt": "2026-11-20T08:00:01Z", "finishedAt": null }Lỗi + xử lý
| Mã | Khi nào | Xử lý |
|---|---|---|
401 | Thiếu khóa, sai, đã thu hồi hoặc hết hạn | Dừng, xin khóa mới – không thử lại |
403 | Khóa của site khác, hoặc việc cả máy bằng khóa site | Dừng, kiểm mã site / xin đúng phạm vi |
404 | Không có site / bản / đường | Kiểm mã site (chữ thường) |
400 | Gói hỏng, thiếu chữ ký, bản đang chạy, site đang có thao tác khác… | Đọc detail; "đang có thao tác khác" thì đợi 10 giây rồi thử lại tối đa 3 lần |
413 | Gói lớn hơn giới hạn | Dùng delta |
5xx / mất kết nối | Máy chủ đang khởi động lại (vd. nâng cấp SiSuHost) | Đợi 15 giây, thử lại tối đa 5 lần với yêu cầu chỉ đọc; không gửi lại gói khi chưa biết lần trước đã nhận chưa – kiểm GET /sites/{mã} trước |
Quy tắc cho agent
- Chỉ thao tác site được giao. Không gọi
stop,rollback, việc cả máy hay nối kho khi không được yêu cầu. - Một site một lần deploy tại một thời điểm; đợi bản trước có kết quả rồi mới gửi bản sau.
- Không coi
202là xong – xong là khi bản ởwatching/succeeded. - Site
signedPackagesOnly: true(đã ghim khóa ký gói / nối kho phát hành): không tự deploy gói tự build – báo người. - Báo kết quả kèm: mã site, số bản, phiên bản, trạng thái cuối; hỏng thì kèm
error+ 30 dòng log cuối (không kèm khóa). - Không in khóa API ra log / câu trả lời; không ghi khóa vào tệp trong repo.
Script mẫu PowerShell (gói nguyên khối)
Đầy đủ một lượt: publish → zip → tải lên → đổi bản → dò. Bản có delta: src/SiSuHost/sisuhost-pack.ps1 -Project <csproj> -Site <mã> -Push https://host.sisunext.vn -Key $env:SISUHOST_API_KEY.
$ErrorActionPreference = 'Stop'
$api = 'https://host.sisunext.vn/api/v1'
$site = 'shop'
$auth = @{ Authorization = "Bearer $env:SISUHOST_API_KEY" }
dotnet publish ./MyShop.csproj -c Release -o ./out
Compress-Archive -Path ./out/* -DestinationPath ./goi.zip -Force
$status = Invoke-RestMethod "$api/sites/$site" -Headers $auth
if ($status.signedPackagesOnly) { throw "Site $site chỉ nhận gói đã ký – cần người deploy." }
$received = Invoke-RestMethod "$api/sites/$site/packages" -Method Post -Headers $auth -Form @{ package = Get-Item ./goi.zip }
Invoke-RestMethod "$api/sites/$site/deployments/$($received.number)/deploy" -Method Post -Headers $auth | Out-Null
$deadline = (Get-Date).AddMinutes(10)
do {
Start-Sleep -Seconds 2
$d = Invoke-RestMethod "$api/sites/$site/deployments/$($received.number)" -Headers $auth
} while ($d.state -in 'received', 'starting' -and (Get-Date) -lt $deadline)
if ($d.state -in 'watching', 'succeeded') { "Đạt: $site bản $($d.number) ($($d.version))" }
else {
Invoke-RestMethod "$api/sites/$site/log?lines=30" -Headers $auth
throw "Bản $($d.number) không lên ($($d.state)): $($d.error)"
}