# Bắt đầu với Mini Server

Viết API Python, chạy thử trên máy và triển khai tại /api của dự án.

Nguồn: https://whypik.com/docs/mini-server
Nhóm: Lập trình viên
Phiên bản tài liệu: 2026-10-14.10
Ngôn ngữ: vi

## Chọn dự án và bật Mini Server

Liên kết mục: https://whypik.com/docs/mini-server#section-0

Mở dự án → Mini Server → Kích hoạt Mini Server. Dịch vụ dùng chung dự án và gói tài khoản, nhưng không trừ dung lượng Hosting hoặc Object Storage.

API có địa chỉ https://<hostname-dự-án>.whypik.app/api. Không cần bật Static Hosting để dùng API. Nếu đã có website trên cùng tên miền, gọi đường dẫn /api/... ngay trong website.

Dùng bộ chọn cạnh tiêu đề để chọn backend hoặc bấm Tạo backend ở cuối danh sách. Mục vượt hạn mức được làm mờ nhưng vẫn bấm để xem cách nâng cấp. Bấm bên ngoài hoặc Escape để đóng bộ chọn; có thể dùng phím mũi tên để di chuyển. Backend bổ sung có địa chỉ https://<mã-backend>.whypik.app/api riêng; chỉ backend mặc định dùng /api của Project. Mọi backend vẫn dùng chung Auth và Database của Project. Tạo thêm không tự thêm origin Auth.

Runtime chạy CPython 3.14, SDK WhyPik và bộ thư viện đã ghim trong sandbox riêng của backend; xem bài Thư viện Python có sẵn. Có HTTPS đi ra ngoài trong handler theo giới hạn của bài Gọi HTTPS và dịch vụ bên ngoài. Chưa hỗ trợ cài thư viện tùy ý, WebSocket, cron hay tiến trình nền liên tục.

**Kết quả cần thấy:** Bạn thấy địa chỉ API và nút triển khai ZIP.


## Cài WhyPik CLI và khởi tạo mã nguồn

Liên kết mục: https://whypik.com/docs/mini-server#section-1

Cần Python 3.11 trở lên trên máy. Sao chép UUID tại Tổng quan dự án, thay PROJECT_UUID trong lệnh. init tạo server.py và cấu hình chỉ chứa địa chỉ WhyPik/UUID; không ghi mật khẩu hay khóa vào cấu hình.

Để dùng backend bổ sung, sao chép Service ID trong dashboard, rồi dùng whypik init my-api --project PROJECT_UUID --service SERVICE_UUID. Các lệnh deploy, logs và rollback nhận --service UUID để chọn rõ backend; bỏ tham số dùng cấu hình hoặc backend mặc định. Cấu hình không chứa khóa.

WhyPik CLI dùng lệnh chính whypik; whypik-mini vẫn là alias tương thích. Package whypik-mini phiên bản 0.3.0rc2 giữ import Python và đường dẫn tải. init mới tạo whypik.toml; thư mục đã có .whypik-mini.json tiếp tục dùng trực tiếp, không chạy init lại.

Dùng whypik run để chạy Mini Server local; dev và runserver trả hướng dẫn chuyển sang run. Triển khai chọn rõ whypik deploy --target api hoặc --target hosting. whypik.toml chứa UUID Project, backend/website, thư mục và mục tiêu mặc định; nhiều target mà chưa chọn rõ sẽ báo lỗi, không tự deploy cả hai. Chạy whypik --help để xem lệnh đang hỗ trợ. Với nhiều backend, dùng --service để chọn rõ.

```
python -m pip install https://app.whypik.com/api/v1/public/sdk/mini/whypik-mini.zip
whypik init my-api --project PROJECT_UUID
cd my-api
```

**Kết quả cần thấy:** Thư mục my-api có server.py, whypik.toml và .env.example.

- [Tải WhyPik CLI và Python SDK](https://whypik.com/api/v1/public/sdk/mini/whypik-mini.zip)

## Viết và chạy thử API

Liên kết mục: https://whypik.com/docs/mini-server#section-2

Lưu mã vào server.py, chạy whypik run rồi mở http://127.0.0.1:8787/api/hello. Có thể chọn whypik run --host 127.0.0.1 --port 8000; --host 0.0.0.0 cho thiết bị khác truy cập qua IP LAN của máy. Chạy lại request sau khi lưu mã để nhận phiên bản mới.

run đọc .env tại thư mục cấu hình, hoặc file chỉ định bằng --env-file; biến terminal ưu tiên. Không chạy lệnh shell hay nội suy biến trong file. Python đọc os.environ. Khởi động lại run sau khi sửa biến; không commit file secret và không đưa vào thư mục build Hosting. Không truyền --db-env thì workspace cũ vẫn dùng Database hosted đã cấu hình. Bản CLI có Migration hỗ trợ --db-env local với stack riêng; xem bài Bắt đầu với Database Migration, không có fallback từ local sang hosted.

Local run chạy mã của bạn với quyền tài khoản trên máy; chỉ dùng cho mã bạn tin cậy. Runtime trên WhyPik có sandbox riêng.

```
from whypik import api, Request

@api.get("/hello")
async def hello(request: Request):
    return {"message": "Hello WhyPik"}
```

**Kết quả cần thấy:** Trình duyệt trả JSON {"message":"Hello WhyPik"}.


## Triển khai lên WhyPik

Liên kết mục: https://whypik.com/docs/mini-server#section-3

Trong Gói & API tài khoản, tạo Loại key CI/CD · Mini Server, chọn đúng dự án/backend và đặt secret vào WHYPIK_DEPLOY_KEY của terminal hoặc CI. Ghi service UUID vào whypik.toml. Khóa quản lý WHYPIK_CLOUD_KEY cũ vẫn dùng được cho thao tác thủ công; không đưa khóa vào website, source hay Git.

CLI đóng gói mã, tải lên và chờ kết quả. Hoặc dùng nút triển khai ZIP trong dashboard: ZIP chứa đúng một server.py, có thể nằm trong thư mục bọc ngoài; hỗ trợ .py, .json, .txt, tối đa 64 file và 1 MB mã giải nén, ZIP tối đa 2 MB.

WhyPik kiểm tra trong sandbox rồi mới đổi phiên bản hoạt động. Bản lỗi không thay bản đang chạy. CLI đọc trạng thái theo đúng deployment UUID và chỉ báo thành công khi bản đó hoạt động. Nếu mất kết nối, gửi lại cùng mã yêu cầu; xem quy tắc retry và thứ tự pipeline trong bài API Hosting, Storage và Project.

CLI mới và Dashboard tải ZIP theo các phần 256 KiB, kiểm SHA-256 từng phần và toàn file. Khi mất mạng, chọn lại đúng ZIP trên cùng trình duyệt/tài khoản/backend rồi bấm triển khai; các phần đã nhận được bỏ qua. Biên nhận lưu 48 giờ tính từ lúc bắt đầu, không gia hạn khi thử lại. Nếu đổi file hoặc hết hạn, cần lượt triển khai mới.

CLI in Deployment idempotency key trước khi gửi. Khi lỗi kết nối, chạy lại whypik deploy --target api --idempotency-key UUID_DA_IN với cùng source, tài nguyên và API key; không tự tạo key khác. Pipeline cùng lần chạy dùng key ổn định. ZIP cũ đã nhận xong chỉ trả lại bản triển khai đó; trạng thái failed cần sửa source và tạo lần mới.

Mỗi lượt mới đặt chỗ một phiên bản và một lần triển khai tháng ngay khi được nhận. Trong lúc tải, dung lượng tính cả ZIP gốc và tối đa 2 MiB cho ZIP chuẩn hóa; phần đặt chỗ giảm sau khi xác minh, phần tạm chỉ trả sau khi dọn xong. Hủy bằng xóa bản đang tải trong Các bản triển khai. Lượt bỏ dở được dọn sau khi hết hạn; tải tiếp không tính thêm lần triển khai.

```
whypik deploy --target api
```

**Kết quả cần thấy:** Phiên bản hiện Sẵn sàng và đang hoạt động; địa chỉ API trả JSON.


## Gọi API và xem kết quả

Liên kết mục: https://whypik.com/docs/mini-server#section-4

Các đường dẫn /api và /api/* dành riêng cho Mini Server; không rơi về index.html khi không tìm thấy API. Auth và Data API vẫn sử dụng /.whypik/auth/* và /.whypik/data/*.

Với ứng dụng ở tên miền khác, thêm origin được phép trong dự án/Auth. Token phải thuộc chính dự án này. Không gửi khóa quản lý tài khoản vào request API khách hàng.

Bấm biểu tượng sao chép cạnh endpoint để lấy địa chỉ API. Các tab Tổng quan, Các bản triển khai, Nhật ký Mini Server, Variables, Sử dụng và Cài đặt dùng gạch chân để chỉ tab đang chọn; trên màn hình hẹp có thể cuộn ngang.

Mini Server có quyền Admin Database. Token chỉ cung cấp request.user đã xác thực; handler phải tự kiểm quyền nghiệp vụ. Không mặc định trả toàn bộ dữ liệu chỉ vì có người gọi API.

```
const result = await fetch("/api/hello");
console.log(await result.json());

// Với handler /products/{id} ở bài SDK, dùng token Project Auth:
await fetch("/api/products/1", {
  headers: { Authorization: `Bearer ${accessToken}` }
});
```

**Kết quả cần thấy:** API trả kết quả do handler cho phép; lỗi và thời gian chạy có trong Nhật ký.


## Quay về phiên bản trước hoặc tạm dừng

Liên kết mục: https://whypik.com/docs/mini-server#section-5

Trong Các phiên bản, chọn phiên bản Sẵn sàng rồi kích hoạt để rollback. Xóa bản cũ để nhường chỗ cho lịch sử mới; không xóa được bản đang hoạt động.

Tạm dừng chặn request mới. Request đã bắt đầu có thời hạn hữu hạn để kết thúc; request đang chờ phải kiểm lại trạng thái trước khi chạy. Xóa Project sẽ dừng runtime, hủy sandbox được giữ lại và xóa mã triển khai cùng các dịch vụ của dự án.

Ngân sách Mini Server là hạn mức vận hành đợt thử nghiệm: mặc định Free 1, Starter 5, Pro 20 backend trên toàn tài khoản, tính cả backend đang tạm dừng. Tạm dừng không trả suất. Số request, bytes, dung lượng và mức đồng thời cộng chung theo tài khoản; không nhân theo backend.

Hạ gói ưu tiên backend mặc định; mục dư bị khóa phục vụ/triển khai. Chủ tài khoản vẫn xuất được mã hoặc xóa backend bổ sung và mọi phiên bản của nó; chờ runtime dọn xong mới trả suất. Backend mặc định không xóa riêng; có thể tạm dừng hoặc xóa Project. Không tự xóa dữ liệu khi hạ gói.

```
whypik logs
whypik rollback DEPLOYMENT_UUID
```

**Kết quả cần thấy:** Bạn thấy phiên bản được chọn đang hoạt động, hoặc trạng thái dịch vụ đã tạm dừng.


## Đọc tiếp

- [Đọc tình trạng dịch vụ trong Project](https://whypik.com/docs/service-status)
- [Data API: chọn cột, lọc và phân trang](https://whypik.com/docs/data-queries)
- [CI/CD với GitHub, GitLab và Bitbucket](https://whypik.com/docs/cicd)
- [Variables và môi trường local](https://whypik.com/docs/mini-server-variables)
- [Thư viện Python có sẵn](https://whypik.com/docs/mini-server-libraries)
- [Mini Server: API và SDK Python](https://whypik.com/docs/mini-server-sdk)
- [Quản lý Mini Server](https://whypik.com/docs/mini-server-admin)
- [Gọi HTTPS và dịch vụ bên ngoài](https://whypik.com/docs/mini-server-https)
- [Admin SDK: Database của Project](https://whypik.com/docs/data-admin)
- [Bắt đầu với Database Migration](https://whypik.com/docs/data-migrations)