SiSuHost · API triển khai /api/v1

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 viLàm đượcDùng cho
Một siteMọi đường /sites/{mã}/… của đúng site đó. Site khác, việc cả máy: 403Agent deploy một ứng dụng – nên dùng
Cả máyMọi site + /host, /apps, /tasks, nối kho /sites/{mã}/feed. Đứng thay mật khẩu xác nhậnNgười vận hành / công cụ của nhà cung cấp
Khóa là bí mật cấp quản trị: không in ra log, không ghi vào repo, không đặt trong URL. Đọc từ biến môi trường 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

  1. Kiểm site: GET /sites/{mã} → 200. Đọc signedPackagesOnly: true nghĩ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.
  2. Đóng gói: dotnet publish -c Release -o out (xem Chuẩn bị gói).
  3. Gửi: thư mục out qua delta (khuyên dùng – chỉ gửi tệp đổi), hoặc nén zip rồi POST /sites/{mã}/packages. Kết quả: bản mới số number, trạng thái received.
  4. Đổi bản: POST /sites/{mã}/deployments/{number}/deploy → 202.
  5. Dò mỗi 2 giây GET /sites/{mã}/deployments/{number} tới khi state là watching hoặc succeeded (đạt) hoặc failed / quarantined (hỏng). Giới hạn 10 phút.
  6. 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.
  7. Kiểm thật (tùy chọn): gọi trang / /health củ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_Data giữ 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 data của site (đường dẫn ở biến môi trường SISUHOST_DATA) hoặc App_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.

GET/sitessite · cả máy

Danh sách site khóa này thấy được (khóa site chỉ thấy site của nó).

GET/sites/{mã}site · cả máy

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"
}
POST/sites/{mã}/packagessite · cả máy

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
POST/sites/{mã}/deployments/{số}/deploysite · cả máy

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.

GET/sites/{mã}/deployments/{số}site · cả máy

DeploymentReport của một bản – dò cái này sau khi đổi bản.

GET/sites/{mã}/operationsite · cả máy

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ó.

POST/sites/{mã}/rollback · restart · start · stopsite · cả máy

rollback quay về bản trước, restart khởi động lại (cả hai chạy nền, 202); start / stop trả 200.

GET/sites/{mã}/log?lines=200site · cả máy

Văn bản đuôi log của ứng dụng (1 – 5000 dòng).

POST/sites/{mã}/updatesite · cả máy

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.

POST/sites/{mã}/delta/plansite · cả máy

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 }
POST/sites/{mã}/deltasite · cả máy

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ĩaAgent làm gì
receivedĐã nhận + kiểm gói, chưa chạyGọi …/deploy
startingĐang chạy ở khe mới, chờ kiểm sốngDò 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õiXong
failedKhông lên được – site vẫn chạy bản cũĐọc error + log, báo người
quarantinedHỏ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.

GET/hostcả máy

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.

POST/host/updatecả máy

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ị.

POST/appscả máy

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": "…" }
PUT/sites/{mã}/feedcả máy

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).

GET/tasks/{id}cả máy
{ "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àoXử lý
401Thiếu khóa, sai, đã thu hồi hoặc hết hạnDừng, xin khóa mới – không thử lại
403Khóa của site khác, hoặc việc cả máy bằng khóa siteDừng, kiểm mã site / xin đúng phạm vi
404Không có site / bản / đườngKiểm mã site (chữ thường)
400Gó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
413Gói lớn hơn giới hạnDùng delta
5xx / mất kết nốiMá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 202 là 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)"
}