Biến môi trường và secret khi deploy: dùng .env an toàn
Cách an toàn để dùng biến môi trường khi deploy là: không bao giờ commit file .env, chỉ commit .env.example có tên biến; đặt giá trị thật trên nền tảng (portal, zo vars set hoặc công cụ set_variables của MCP), dùng biến tham chiếu cho chuỗi kết nối database thay vì chép tay, gom khoá dùng chung vào biến chung của environment, và có sẵn quy trình xoay khoá khi lộ. Bài này đi qua từng bước trên ZoCloud.
Vì sao không commit file .env
File .env thường chứa thứ quý nhất của app: mật khẩu database, khoá API thanh toán, khoá AI, secret ký phiên đăng nhập. Khi file này lên Git:
- Ai đọc được repo (đồng nghiệp cũ, freelancer, CI bên thứ ba) đều có khoá.
- Xoá file ở commit sau không xoá nó khỏi lịch sử. Phải coi khoá đã lộ và đổi khoá.
- Repo công khai bị các bot quét khoá API liên tục; khoá AI lộ có thể bị dùng hết hạn mức trong vài giờ.
Với vibe coder, rủi ro còn đến từ AI agent: agent đọc thư mục, thấy .env, và có thể dán giá trị vào code hay vào câu trả lời. Quy tắc đơn giản: code đọc từ process.env (hay os.environ), giá trị nằm trên nền tảng deploy.
Chuẩn bị repo
# .gitignore
.env
.env.*
!.env.example
# .env.example: chỉ tên biến, không có giá trị thật
DATABASE_URL=
OPENAI_API_KEY=
SESSION_SECRET=
.env.example giúp người mới (và agent) biết app cần biến gì mà không lộ gì.
ZoCloud xử lý .env thế nào
Khi deploy từ máy bằng zo deploy, zo đóng gói thư mục và không bao giờ gửi file .env* (trừ .env.example); nó cũng bỏ qua .git, node_modules và các mẫu trong .gitignore, .zocloudignore, .dockerignore. Nghĩa là dù bạn quên, file .env trên máy không đi lên máy chủ.
Biến bạn đặt trên ZoCloud:
- được mã hoá khi lưu;
- dùng được cả lúc build và lúc chạy;
- có hiệu lực từ lần deploy sau (đổi biến xong cần deploy lại).
Ba cách đặt biến môi trường
1. Trên portal
Mở service → tab Biến môi trường:
- Thêm biến để thêm từng biến.
- Sửa dạng .env để dán nhiều dòng
KEY=valuemột lúc (tiện khi chuyển từ file.envtrên máy); Dạng bảng để quay lại.
Sau khi lưu, bấm Deploy để bản mới nhận biến.
2. Bằng zo CLI
zo link myorg/shop/web
zo vars # liệt kê biến
zo vars set STRIPE_KEY=sk_live_xxx SESSION_SECRET=chuoi-ngau-nhien
zo vars unset OLD_KEY
zo deploy
Mẹo: lệnh zo vars set có giá trị bí mật sẽ nằm trong lịch sử shell. Trên máy dùng chung, hãy xoá dòng đó khỏi lịch sử hoặc dán qua portal.
Trong CI, không đăng nhập bằng tay mà đặt token vào secret của CI và truyền qua biến ZOCLOUD_TOKEN:
- run: zo deploy -to myorg/shop/web
env:
ZOCLOUD_TOKEN: ${{ secrets.ZOCLOUD_TOKEN }}
Xem đủ các lệnh ở tài liệu zo CLI.
3. Qua AI agent (MCP)
Khi Claude Code, Cursor hay ChatGPT deploy cho bạn qua MCP server của ZoCloud, agent đặt biến bằng công cụ set_variables (giá trị rỗng là xoá biến, hỗ trợ cả ${{tên.DATABASE_URL}}). Agent không cần đọc file .env của bạn.
Một số nguyên tắc khi giao cho agent:
- Tạo token riêng cho agent, giới hạn trong một tổ chức, số ngày ngắn (cách tạo token). Agent chỉ cần xem log thì dùng token Chỉ đọc: mọi công cụ thay đổi, kể cả
set_variables, bị từ chối. - Khoá AI tạo bằng công cụ
create_ai_keychỉ hiện một lần; agent nên đặt thẳng vào biến bằngset_variablesthay vì in ra. - Đừng dán khoá thật vào khung chat nếu không cần: bạn có thể tự đặt khoá trên portal rồi bảo agent "dùng biến
OPENAI_API_KEYđã có".
Đọc thêm: MCP server là gì và deploy từ ChatGPT, Claude.
Biến tham chiếu: không chép tay chuỗi kết nối
Chép chuỗi kết nối database vào biến là cách dễ sai và dễ lộ nhất. ZoCloud cho bạn trỏ thẳng tới tài nguyên trong cùng environment:
| Tham chiếu | Giá trị |
|---|---|
${{pg.DATABASE_URL}} |
chuỗi kết nối của database tên pg |
${{cache.REDIS_URL}} |
Valkey tên cache |
${{files.S3_BUCKET}}, ${{files.S3_ACCESS_KEY_ID}}… |
bucket tên files |
${{api.PRIVATE_URL}} |
http://api.internal, gọi qua mạng nội bộ |
${{api.PUBLIC_URL}} |
địa chỉ https://…zocloud.app của service api |
${{api.TÊN_BIẾN}} |
một biến thường của service api |
Ví dụ thêm PostgreSQL cho app:
zo db create pg -engine postgres
zo vars set 'DATABASE_URL=${{pg.DATABASE_URL}}'
zo deploy
Dùng dấu nháy đơn để shell không hiểu ${{…}} là biến của shell. Lợi ích: bạn không bao giờ phải nhìn thấy mật khẩu database, và giá trị tự cập nhật nếu database đổi máy chủ hay mật khẩu. Chi tiết ở tài liệu database và bài PostgreSQL cloud tại Việt Nam.
Biến chung theo environment
Project có nhiều service (web, worker, cron) thường cùng dùng một khoá: DSN Sentry, khoá gửi e-mail, khoá AI. Đặt khoá ở từng service thì khi đổi phải sửa nhiều nơi và dễ sót.
Đặt một lần ở Cài đặt project → Biến chung (theo environment đang xem), hoặc:
zo vars --shared set SENTRY_DSN=https://... OPENAI_API_KEY=zcai_...
zo vars --shared # xem biến chung
Rồi trong biến của từng service:
SENTRY_DSN=${{shared.SENTRY_DSN}}
OPENAI_API_KEY=${{shared.OPENAI_API_KEY}}
Cách hoạt động cần biết:
- Đổi một biến chung: các service đang chạy có tham chiếu tới nó tự deploy lại. Service chưa deploy hoặc đang deploy lấy giá trị mới ở lần deploy kế tiếp.
- Mỗi environment có biến chung riêng. Environment mới (ví dụ
staging) sao chép biến chung của environment gốc; bạn nên đổi ngay các khoá production sang khoá thử nghiệm. - Preview cho pull request đọc biến chung của chính nó trước, rồi của environment nó preview.
sharedlà tên dành riêng: không đặt tên service, database hay bucket làshared.
Tách khoá production và staging
Một lỗi hay gặp: staging dùng chung khoá thanh toán thật với production. Hãy để mỗi environment có bộ khoá riêng:
- Tạo environment
staging(hướng dẫn staging và preview). - Chọn environment
stagingtrên canvas, mở Cài đặt project → Biến chung, thay các khoá bằng khoá test của nhà cung cấp. - Với khoá AI, tạo một key riêng cho staging ở mục AI với Hạn mức mỗi tháng (VND) thấp, để lỗi vòng lặp ở staging không đốt tiền.
Xoay khoá (rotate) mà không gián đoạn
Nên xoay khoá định kỳ, và bắt buộc khi có người rời nhóm hoặc nghi lộ. Quy trình chung:
- Tạo khoá mới ở nhà cung cấp (giữ khoá cũ còn hiệu lực).
- Cập nhật biến trên ZoCloud. Nếu là biến chung, các service dùng nó tự deploy lại; nếu là biến của service, bấm Deploy hoặc
zo deploy. - Kiểm tra: tab Log hoặc
zo logs -q "401"để chắc không còn lỗi xác thực. - Thu hồi khoá cũ ở nhà cung cấp.
Bản đang chạy vẫn phục vụ cho tới khi bản mới khoẻ, nên bước 2 không làm sập app; nếu bản mới lỗi vì khoá sai, bản cũ vẫn chạy và bạn sửa lại biến.
Với khoá AI gateway của ZoCloud: mục AI → Tạo key cho khoá mới, đặt vào biến, rồi Thu hồi key cũ (ứng dụng đang dùng key cũ ngừng gọi được ngay, nên làm sau khi deploy xong). Nếu chỉ muốn chặn tạm, bạn có thể tắt key thay vì thu hồi. Xem tài liệu AI gateway.
Khi khoá đã lộ trên Git
- Xoay khoá ngay theo bốn bước trên. Đây là việc quan trọng nhất; làm sạch lịch sử Git là việc phụ.
- Thêm
.envvào.gitignore, xoá file khỏi repo. - Nếu repo công khai hoặc đã chia sẻ, cân nhắc viết lại lịch sử Git; nhưng vẫn coi khoá cũ là đã lộ.
- Xem mục Hoạt động của tổ chức để biết ai đã đổi biến và deploy gần đây.
Biến do ZoCloud đặt sẵn
Một số biến ZoCloud tự đặt và bạn không ghi đè được: PORT (app phải nghe trên cổng này), ZOCLOUD_SERVICE_NAME, ZOCLOUD_PUBLIC_DOMAIN, ZOCLOUD_DEPLOYMENT_ID, ZOCLOUD_GIT_COMMIT_SHA (khi build từ Git), ZOCLOUD_VOLUME_MOUNT_PATH (khi có volume). Dùng ZOCLOUD_GIT_COMMIT_SHA để gắn phiên bản vào báo lỗi, rất tiện khi điều tra sự cố.
Danh sách kiểm tra nhanh
-
.envtrong.gitignore, có.env.example. - Không có khoá nào viết thẳng trong code (tìm
sk_,zcai_,password=). - Chuỗi kết nối database dùng
${{pg.DATABASE_URL}}, không chép tay. - Khoá dùng chung nằm ở Biến chung, service tham chiếu bằng
${{shared.KEY}}. - Staging có khoá riêng, khoá AI có hạn mức.
- Token cho CI và agent giới hạn một tổ chức, có hạn dùng.
- Có quy trình xoay khoá và đã thử ít nhất một lần.
Câu hỏi thường gặp
Có nên commit file .env lên GitHub không? Không. File .env chứa mật khẩu và khoá API; đã lên repo là coi như đã lộ, kể cả khi xoá ở commit sau. Hãy commit .env.example chỉ có tên biến và đặt giá trị thật trên nền tảng deploy.
zo deploy có gửi file .env lên ZoCloud không? Không. zo deploy không bao giờ gửi các file .env* (trừ .env.example). Bạn đặt biến bằng zo vars set, trên tab Biến môi trường của service, hoặc để AI agent dùng công cụ set_variables.
Biến chung của environment dùng thế nào? Đặt giá trị một lần ở Cài đặt project → Biến chung (hoặc zo vars --shared set KEY=value), rồi trong biến của từng service ghi ${{shared.KEY}}. Đổi biến chung thì các service đang chạy có tham chiếu tới nó tự deploy lại.
Lỡ lộ khoá API thì làm gì? Tạo khoá mới ở nhà cung cấp, cập nhật biến trên ZoCloud (deploy lại nếu là biến của service), kiểm tra app chạy với khoá mới rồi thu hồi khoá cũ. Sau đó xem lại lịch sử repo và log để biết khoá đã bị lộ ở đâu.
Tài liệu liên quan: App, biến môi trường và deploy, zo CLI và MCP.