Cloudflare API Token cho 2server: 5 quyền Zone sống còn
Deploy web công khai qua Cloudflare hay kẹt ở 401/403 dù token verify "active". Gốc rễ: quyền Account không kéo theo quyền Zone, và một web public cần đúng 5 quyền Zone tối thiểu — không hơn, không kém.
Vấn đề: token "active" nhưng deploy vẫn 403
Ai từng tự deploy một site lên VM với domain đặt ở Cloudflare chắc đều gặp một trong hai cực đoan:
- Cực đoan một: deploy bị chặn với 401/403 bí ẩn. Bạn tạo API Token, chạy
verify, thấystatus: "active", thở phào — rồi bước ghi DNS hay chỉnh SSL vẫn trả về lỗi quyền. - Cực đoan hai: chán chán thì dùng luôn Global API Key — thứ có quyền làm mọi thứ trên tài khoản Cloudflare của bạn. Deploy chạy được, nhưng từ đó một chuỗi khóa master nằm trong config, và nếu nó lộ thì không chỉ cái zone đó mà cả account của bạn đi theo.
Cả hai đều bắt nguồn từ cùng một chỗ hiểu nhầm về cách Cloudflare phân quyền. Tài liệu Cloudflare token của 2server vạch ra con đường đúng: token theo nguyên tắc quyền hạn tối thiểu (least privilege), đúng 5 quyền Zone cho một web public, và token đó không bao giờ nằm trong git.
Bẫy một: quyền Account không kéo theo quyền Zone
Dashboard của Cloudflare khi tạo API Token chia quyền thành các nhóm theo scope: Account và Zone. Đây là chỗ dễ nhầm nhất:
Tick một quyền ở mục Account KHÔNG tự động cấp quyền tương ứng ở mục Zone.
Hai tầng này độc lập. Một token chỉ có quyền Account vẫn hoàn toàn "hợp lệ" — gọi API danh tính ngon lành — nhưng không ghi được vào zone nào. Đây chính là nguyên nhân của một đống report "token active mà vẫn 403".
Khi cấp quyền cho 2server, bạn cần để mắt cả hai thứ:
- Nhóm quyền nào — Account hay Zone.
- Scope area nào — "All zones" hay "Specific zone" (khuyến nghị khóa vào đúng zone bạn deploy, nếu có lựa chọn).
Năm quyền Zone thiết yếu cho một web public
Với một deploy web công khai chuẩn — trỏ DNS, bật SSL đúng chuẩn, dọn cache, cấp chứng chỉ gốc — tài liệu 2server liệt kê đúng 5 quyền ở nhóm Zone:
| # | Quyền | Để làm gì |
|---|---|---|
| 1 | Zone — Zone — Read | Đọc thông tin zone; bước cơ sở để các thao tác khác xác định đúng zone |
| 2 | Zone — DNS — Edit | Ghi/cập nhật bản ghi DNS trỏ về VM |
| 3 | Zone — Zone Settings — Edit | Chỉnh các cài đặt mức zone (ví dụ bật strict SSL) |
| 4 | Zone — Cache Rules — Edit | Quản lý cache rule / purge cache sau deploy |
| 5 | Zone — SSL and Certificates — Edit | Cấp chứng chỉ Origin CA cho kết nối Cloudflare ↔ origin |
Mỗi quyền gắn với một việc cụ thể trong deploy. Thiếu quyền nào thì đúng bước đó chết với 403 — và đó là tín hiệu tốt, vì nó chỉ thẳng vào quyền cần thêm.
Token cho việc khác: Email Routing, Workers, D1
Nguyên tắc tối thiểu quyền cắt cả chiều ngang, không chỉ chiều dọc. Nếu dự án của bạn dùng thêm Email Routing hay Workers/D1, những tính năng này có nhóm quyền riêng — bạn cấp thêm đúng quyền đó cho đúng scope cần dùng, thay vì tăng quyền toàn cục.
Nói cách khác: bản đồ quyền đi theo bản đồ tính năng. Web tĩnh → 5 quyền Zone ở trên. Thêm email routing → thêm quyền Email Routing. Thêm worker/D1 → thêm quyền tương ứng. Không tính năng nào thì không quyền nào.
Bẫy hai: "verify active" không đồng nghĩa "có quyền ghi"
Cloudflare có endpoint kiểm tra token — gọi GET /user/tokens/verify và nhận về "status": "active". Nhiều người coi đây là dấu xác nhận "token đủ dùng". Không phải.
Verify chỉ chứng minh danh tính: token tồn tại, chưa bị thu hồi, thuộc account đúng. Nó không nói gì về việc token có quyền ghi DNS hay cấp cert trên zone của bạn không. Một token rỗng quyền Zone vẫn verify "active" ngon lành.
Vì vậy khi gỡ lỗi quyền:
- Verify để loại trừ token chết/sai account.
- Nếu vẫn 403 → mở dashboard, xem lại đúng nhóm quyền (Account vs Zone) và scope của token.
- Thêm đúng quyền còn thiếu — chứ không cấp lại token mới "cho chắc".
Đừng vá lỗi quyền bằng Global API Key hoặc token admin
Khi gặp 403, phản xạ "tạm thời cho quyền to để chạy đã" rất dễ hiểu — và rất nguy hiểm. Global API Key hay một token với quyền admin rộng sẽ:
- Nằm lại trong config/script lâu hơn bạn tưởng ("tạm" hóa "vĩnh viễn").
- Biến một vụ lộ file cấu hình thành lộ toàn bộ account Cloudflare.
Cách vá đúng nhỏ hơn nhiều: đọc thao tác nào đang 403, thêm chính xác quyền đó vào token hiện có. Chi phí là một cú tick trong dashboard; cái bạn mua được là token vẫn nằm trong phạm vi một zone.
Nạp token: không git, không manifest — 2srv server env
Nửa còn lại của bài toán là token nằm ở đâu. Tài liệu 2server rõ ràng: không lưu token trong manifest cấu hình, không commit vào git. Cách nạp đúng là đưa token vào file .env private trên máy, rồi nạp vào server qua:
2srv server envLuồng đầy đủ gọn trong bốn bước:
- Tạo API Token trên dashboard với đúng 5 quyền Zone (và scope đúng zone nếu được).
- Lưu token vào file
.envprivate trên máy của bạn — file này không commit. - Nạp lên server bằng
2srv server env. - Deploy. Nếu gặp 403 → quay lại bước phân tích quyền thiếu, thêm đúng quyền, không nới rộng token.
Token nằm đúng chỗ: trong biến môi trường của server, không trong repo, không trong manifest ai cũng đọc được.
Checklist trước khi deploy
- Token là API Token, không phải Global API Key.
- Đủ 5 quyền ở nhóm Zone: Zone Read, DNS Edit, Zone Settings Edit, Cache Rules Edit, SSL & Certificates Edit.
- Scope khóa vào zone deploy (nếu dashboard cho chọn).
- Quyền riêng cho Email Routing / Workers / D1 chỉ khi dùng tới.
- Verify "active" chỉ là bước kiểm tra danh tính, không phải kiểm tra quyền.
- Token trong
.envprivate, nạp qua2srv server env, không commit git.
Bước tiếp theo
Nếu bạn đang để Cloudflare token trong manifest, hoặc đang dùng Global API Key vì "cho nó chạy" — đây là lúc thu nó lại thành một API Token 5 quyền Zone rồi nạp qua 2srv server env. Tài liệu đầy đủ: 2found.dev/docs/2server/cloudflare-tokens.
