Dùng Claude Code, Cursor deploy lên server an toàn
Cách dùng Claude Code, Cursor deploy lên server: để agent chuẩn bị repo và push lên Git, server tự deploy khi push hoặc từ CI, không phải đưa key server cho AI.

Ý chính
- Cách an toàn nhất để deploy bằng Claude Code hay Cursor là để agent sửa repository và push lên Git, còn server tự deploy từ Git, nhờ vậy agent không bao giờ giữ thông tin đăng nhập server.
- Một repository deploy được phải lắng nghe trên cổng trong biến $PORT, đọc cấu hình từ biến môi trường, có lệnh build và start rõ ràng, có đường dẫn health check và .gitignore chặn file bí mật.
- Claude Code đọc CLAUDE.md hoặc AGENTS.md ở đầu mỗi phiên, Cursor đọc AGENTS.md và .cursor/rules, nên quy tắc deploy viết ở đó được áp dụng mọi lần.
- Không bao giờ dán mật khẩu root hay API key vào khung chat; dùng deploy key chỉ đọc, secret của CI và xem lại mọi diff trước khi vào nhánh deploy.
Để dùng Claude Code hay Cursor deploy lên server, hãy để AI agent làm đúng việc nó giỏi là sửa repository, còn việc deploy để server tự làm từ Git. Yêu cầu agent cho app lắng nghe trên $PORT, đọc cấu hình từ biến môi trường, khai báo lệnh build và start, thêm route health check và giữ file bí mật ngoài Git; đưa cho nó tài liệu của nền tảng hosting; rồi bạn xem lại diff và push. Server deploy khi có push qua webhook có chữ ký, hoặc pipeline CI gọi lệnh deploy bằng API token, và agent không bao giờ cần tới mật khẩu root của bạn.
Bài này nói về quy trình và cách giữ an toàn, không gắn với một framework cụ thể. Chi tiết từng framework có trong các bài deploy Node.js lên VPS, deploy app Python lên VPS và Next.js không cần Vercel. Cách Claude Code và Cursor hoạt động được lấy từ tài liệu chính thức của họ tại thời điểm viết (tháng 11/2026).
"Deploy bằng Claude Code" thực ra là gì?
Có hai cách để AI coding agent deploy, và chỉ một cách là nên làm:
| Agent đăng nhập vào server | Agent push lên Git, server tự deploy | |
|---|---|---|
| Agent cần gì | Quyền SSH, thường là root, hoặc mật khẩu panel | Quyền Git bình thường trên máy của bạn |
| Sai một lần thì mất gì | Mọi thứ trên server: file, database, các site khác | Một commit lỗi, sẽ bị health check hoặc rollback chặn lại |
| Lưu vết | Lịch sử shell, nếu còn | Mỗi thay đổi là một commit đọc được và hoàn tác được |
| Lặp lại được không | Tùy lần này agent gõ lệnh gì | Cùng một pipeline chạy cho mọi lần push |
Claude Code và Cursor đều chạy được lệnh shell, nên cột đầu tiên về kỹ thuật là làm được. Nhưng như vậy nghĩa là một mô hình ngôn ngữ, chỉ cần một câu prompt, đang cầm chìa khóa production. Cột thứ hai giữ agent trong repository, nơi mọi việc nó làm đều xem lại được, còn việc deploy giao cho một pipeline lần nào cũng chạy giống nhau.
Bước 1: Đưa cho agent tài liệu của nền tảng
Agent sẽ đoán khi không biết mình deploy lên đâu. Một bản deploy "chạy được trên mọi VPS" thường hỏng ở những chi tiết như bind vào địa chỉ nào, biến nào chứa cổng, nền tảng chạy npm ci hay npm install. Cách khắc phục là đưa cho agent tài liệu chính thức của nền tảng.
Nhiều nền tảng giờ xuất bản tài liệu cho mô hình ngôn ngữ theo quy ước llms.txt. ZoPanel có hai file, mô tả trên trang dành cho developer:
- /llms.txt: mục lục tài liệu, mỗi trang một dòng tóm tắt kèm link tới bản Markdown;
- /llms-full.txt: toàn bộ tài liệu gộp trong một file Markdown.
File đầy đủ khá lớn (khoảng 2 MB tại thời điểm viết), nên với một lần deploy, tốt hơn là để agent đọc mục lục rồi chỉ đọc hai, ba trang cần thiết, ví dụ https://zopanel.net/docs/git-deploy.md và https://zopanel.net/docs/nodejs.md.
Prompt dán thẳng vào Claude Code hoặc Cursor:
Đọc https://zopanel.net/llms.txt, rồi đọc các trang nó liên kết về Git deploy
và về runtime của project này (Node.js, Python, PHP, site tĩnh hoặc Docker).
Chuẩn bị repository này để deploy bằng ZoPanel Git deploy:
1. Cho server lắng nghe trên 127.0.0.1 và cổng trong biến môi trường PORT.
2. Chuyển mọi cấu hình và secret sang biến môi trường. Tạo .env.example chỉ có
tên biến và giá trị mẫu, và bảo đảm .env nằm trong .gitignore.
3. Cho tôi biết lệnh install, build và start mà ZoPanel sẽ nhận diện, và sửa
package.json hoặc Procfile nếu chúng sai.
4. Thêm route health check, ví dụ GET /healthz trả về 200, không cần đăng nhập
và không ghi vào database.
5. Cố định phiên bản runtime (.nvmrc với Node.js).
6. Liệt kê các thư mục app ghi vào khi chạy (uploads, cache) để tôi đặt làm
persistent path.
Không đọc hay in nội dung .env, không chạy git push, và cho tôi xem diff khi xong.
Trong Claude Code, việc đọc URL dùng công cụ WebFetch, công cụ này hỏi bạn cho phép theo từng tên miền, trừ các tên miền đã được duyệt sẵn (tài liệu permissions). Với Cursor, cách đơn giản và chắc chắn nhất là dán URL vào prompt, hoặc tải các trang tài liệu về repository rồi tham chiếu như file bình thường.
Lưu quy tắc lâu dài bằng CLAUDE.md, AGENTS.md hoặc Cursor rules
Prompt sẽ bị quên ở phiên sau. Cả hai công cụ đều đọc file hướng dẫn trong repository:
- Claude Code nạp file
CLAUDE.mdcủa project (hoặc.claude/CLAUDE.md) ở đầu mỗi phiên và có thể import file khác bằng@path/to/file. Nếu repository cóAGENTS.mdmà không cóCLAUDE.md, Claude Code sẽ đọcAGENTS.md(tài liệu memory). - Cursor đọc
AGENTS.mdở thư mục gốc và các thư mục con, cùng các project rule trong.cursor/rules/*.mdc; rule cóalwaysApply: trueđược dùng trong mọi cuộc chat (tài liệu rules).
Vì vậy một file AGENTS.md dùng được cho cả hai:
# Deploy
- Production deploy từ nhánh `main` qua ZoPanel Git deploy.
Tài liệu nền tảng: https://zopanel.net/llms.txt
- Server phải lắng nghe trên 127.0.0.1:$PORT. Không bao giờ hard-code cổng.
- Cấu hình lấy từ biến môi trường; .env.example liệt kê các biến.
- GET /healthz phải trả về 200 nhanh, không đụng tới database.
- Không bao giờ đọc, in ra hay commit .env hoặc file key.
- Làm việc trên nhánh feature. Không bao giờ push lên main; tôi review và merge.
- Migration database phải tương thích ngược với bản release trước.
Cả hai hãng đều coi các file này là hướng dẫn chứ không phải cơ chế cưỡng chế. Tài liệu Claude Code nói rõ điều đó và chỉ sang permission rule và hook khi cần chặn hẳn một việc.
Bước 2: Để agent chuẩn bị repository
Dù deploy lên đâu, một repository deploy suôn sẻ đều có vài đặc điểm giống nhau. Trên ZoPanel, mỗi đặc điểm tương ứng với một thiết lập trong tài liệu Git deploy:
| Yêu cầu | Vì sao | Trên ZoPanel |
|---|---|---|
Lắng nghe trên 127.0.0.1:$PORT |
Nền tảng chọn cổng và đặt proxy phía trước | PORT được đặt riêng cho từng slot blue/green, kèm HOST=127.0.0.1; bản release không trả lời trên cổng đó trong 90 giây sẽ thất bại |
| Cấu hình nằm trong biến môi trường | Secret không vào Git; cùng một code chạy được cho staging và production | Environment variables hoặc Paste .env, có hiệu lực lúc build và lúc chạy |
| Lệnh install, build, start rõ ràng | Nền tảng phải tự build được mà không cần bạn | Nhận diện từ file lock, framework và Procfile; sửa được trong Build & run |
| Có file lock và phiên bản runtime cố định | Build ra kết quả giống nhau mỗi lần | npm ci khi có package-lock.json; phiên bản Node.js lấy từ .nvmrc, .node-version hoặc engines.node |
| Đường dẫn health check | Chỉ chuyển traffic sang bản release chạy được | Đặt Health check path là /healthz; phải trả lời mã dưới 500 trước khi chuyển |
| File sinh ra khi chạy nằm ngoài release | Mỗi lần deploy là một thư mục mới | Persistent paths, ví dụ uploads, .env |
.gitignore chặn file bí mật |
Repository có thể được chia sẻ hoặc public sau này | Không phải tính năng của nền tảng; là việc của bạn |
Ví dụ Express tối giản cho dòng thứ nhất và thứ năm:
const express = require('express');
const app = express();
app.get('/healthz', (req, res) => res.status(200).send('ok'));
// ... các route của bạn
const port = Number(process.env.PORT) || 3000;
app.listen(port, process.env.HOST || '127.0.0.1');
Và file .gitignore mà agent nên thêm hoặc bổ sung:
.env
.env.*
!.env.example
*.pem
*.key
node_modules/
Với Python, lệnh start bind theo cùng cách, ví dụ gunicorn app:app --bind 127.0.0.1:$PORT (tài liệu Python).
Bước 3: Xem lại diff rồi mới push
Đây là bước khiến việc deploy có AI hỗ trợ trở nên an toàn, và chỉ mất vài phút:
- Cho agent làm trên một nhánh feature (
git switch -c deploy-prep). - Tự đọc diff:
git diff main...deploy-prep. Tìm key bị hard-code, lệnh start bị đổi, test bị xóa, dependency mới bạn không yêu cầu, và mọi thứ đụng tới phần đăng nhập, phân quyền. - Chạy thử trên máy với
PORT=4000 npm startvàcurl -i http://127.0.0.1:4000/healthz. - Push nhánh lên và tự merge vào nhánh deploy, qua pull request nếu làm việc theo nhóm.
Vì webhook của ZoPanel chỉ deploy đúng nhánh đã cấu hình, agent có thể thoải mái push các nhánh feature mà không có gì bị đưa lên production. Checklist bảo mật cho vibe coding có danh sách đầy đủ hơn những gì cần soát trong code do AI viết.
Bước 4: Deploy khi push bằng webhook có chữ ký
Pipeline đơn giản nhất: mỗi lần merge vào main là deploy. Trên ZoPanel, mở tab Deploy của website, bật Deploy when main is pushed, chép Payload URL và Secret, rồi thêm webhook trong GitHub (content type application/json), GitLab hoặc Gitea.
ZoPanel kiểm tra chữ ký HMAC X-Hub-Signature-256 của GitHub, hoặc header token của GitLab và Gitea, và không bao giờ nhận secret nằm trên URL. Các lần gửi trùng lặp bị bỏ qua, mỗi 15 giây chỉ khởi động tối đa một lần deploy từ webhook, và không deploy khi đang có lần deploy khác chạy. Mỗi lần deploy build trong một thư mục release mới, trong giới hạn CPU và RAM của tài khoản; bản mới phải qua health check thì nginx mới chuyển sang, và 5 bản gần nhất được giữ lại để rollback bằng một cú bấm. Bài tự động deploy từ GitHub giải thích vì sao từng bước kiểm tra này quan trọng.
Với repository private, hãy dùng deploy key thay vì token cá nhân: ZoPanel hiển thị một public key ở Deploy → Deploy key (private repositories), bạn thêm nó vào repository dưới dạng key chỉ đọc. Trên GitHub, deploy key mặc định chỉ có quyền đọc và chỉ gắn với một repository (tài liệu GitHub).
Cách khác: gọi deploy từ CI bằng API token
Nếu muốn test phải qua rồi mới deploy, hãy để CI gọi lệnh deploy thay cho webhook. Với license trả phí (Pro), tạo token ở My account → API tokens và lưu nó thành secret của repository, không bao giờ để trong code hay trong khung chat. Secret của GitHub Actions được tham chiếu bằng ${{ secrets.NAME }}:
name: test-and-deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
- run: npm ci
- run: npm test
- name: Trigger ZoPanel deploy
run: |
curl -fsS -X POST \
-H "Authorization: Bearer ${{ secrets.ZOPANEL_TOKEN }}" \
"https://panel.example.com:8888/api/sites/${{ secrets.ZOPANEL_SITE_ID }}/app/deploy"
Mỗi website chỉ dùng một trong hai cách, webhook hoặc CI, đừng dùng cả hai; nếu không, một lần push sẽ deploy trước khi test chạy xong. Agent có thể viết workflow này giúp bạn, còn secret thì bạn tự thêm trong phần cài đặt của repository.
Làm sao giữ secret tránh xa AI agent?
Agent thấy mọi thứ bạn dán vào và, tùy quyền được cấp, mọi file nó mở được. Vài quy tắc đúng với mọi công cụ:
- Không bao giờ dán mật khẩu root, mật khẩu panel, API token hay private key vào khung chat. Đặt chúng vào biến môi trường của nền tảng hoặc secret của CI, nơi agent không cần đụng tới.
- Dùng deploy key, không dùng token cá nhân, cho việc server truy cập repository. Một key chỉ đọc cho một repository giới hạn thiệt hại nếu bị lộ.
- Chặn file bí mật ngay trong công cụ. Với Claude Code, thêm deny rule
Read(./.env)vào.claude/settings.json(tài liệu permissions); mặc định Claude Code cũng hỏi trước khi sửa file và trước phần lớn lệnh shell. Cursor bỏ qua các file trong.gitignore, trong danh sách mặc định (có.env*) và trong.cursorignore, nhưng tài liệu của họ cảnh báo việc bảo vệ không được đảm bảo tuyệt đối, và công cụ terminal, MCP vẫn đọc được file bị ignore (tài liệu ignore files). - Không cho agent đụng vào nhánh deploy. Agent push nhánh feature; bạn là người merge.
- Xem lại mọi diff, và thay mới bất kỳ secret nào từng xuất hiện trong commit, kể cả khi sau đó đã xóa.
Deploy bằng ZoPanel
ZoPanel là control panel hosting bạn cài trên VPS của mình. Với app do agent build, nó cho bạn đúng pipeline mô tả ở trên:
- Git deploy tự nhận diện Next.js, Vite, Nuxt, SvelteKit, Express, Django, FastAPI, Flask, Laravel và nhiều framework khác, build trong sandbox, release không downtime sau health check và rollback (tài liệu Git deploy);
- webhook push có chữ ký cho GitHub, GitLab và Gitea, và deploy từ CI bằng API token với license trả phí;
- llms.txt và llms-full.txt để Claude Code hay Cursor đọc tài liệu;
- database, SSL miễn phí và log trong cùng panel, kèm trợ lý AI tùy chọn trong panel, trả lời câu hỏi về website bằng API key Anthropic của chính bạn và chỉ thực hiện thao tác sau khi bạn xác nhận.
Những gì ZoPanel không có: ZoPanel không có MCP server, nên agent làm việc qua Git và API có tài liệu chứ không điều khiển panel trực tiếp. Không có preview deployment, không có CDN toàn cầu, và bạn là người vận hành server. Xem thêm quy trình trên trang vibe coding.
Kết luận
Deploy bằng Claude Code hay Cursor hiệu quả nhất khi agent không bao giờ chạm vào server: nó chuẩn bị repository theo đúng tài liệu của nền tảng, bạn xem lại diff, và Git kích hoạt một lần deploy có health check và hoàn tác được. Viết quy tắc một lần trong AGENTS.md, giữ secret trong biến môi trường và secret của CI, và dùng deploy key chỉ đọc.
Muốn thử trọn quy trình, hãy cài gói Free của ZoPanel (10 website, 10 database, 3 tài khoản hosting) lên một VPS thử nghiệm, dán prompt ở trên vào agent và push kết quả.
Câu hỏi thường gặp
Claude Code có tự deploy app lên server được không?
Claude Code chạy được lệnh shell, nên nó có thể SSH vào server nếu bạn cấp quyền. An toàn hơn là đừng làm vậy: để nó chuẩn bị repository và push một nhánh, còn server tự deploy từ Git, có health check và rollback.
Làm sao đưa tài liệu của nền tảng hosting cho Cursor hay Claude Code?
Chỉ cho nó file llms.txt của nền tảng hoặc các trang Markdown cụ thể, ngay trong prompt hoặc trong AGENTS.md. ZoPanel có /llms.txt (mục lục) và /llms-full.txt (toàn bộ tài liệu trong một file).
Có nên ghi mật khẩu server vào CLAUDE.md hay AGENTS.md không?
Không. Các file này được commit vào repository và nạp vào ngữ cảnh của mô hình. Giữ secret trong biến môi trường của nền tảng hoặc secret của CI, và để .env trong .gitignore.
ZoPanel có MCP server không?
Không. Coding agent làm việc với ZoPanel qua Git deploy, webhook khi push, API dùng token và tài liệu trong llms.txt.
Nếu AI agent làm hỏng production thì sao?
Trên ZoPanel, bản release không qua health check sẽ không bao giờ nhận traffic, bản trước vẫn tiếp tục phục vụ. Nếu bản mới qua health check nhưng chạy sai, bạn rollback về một trong 5 bản gần nhất ở thẻ Releases mà không downtime.
Đưa server của bạn lên ZoPanel
Bắt đầu miễn phí với 10 website trên server Ubuntu hoặc Debian mới, hoặc trao đổi với đội ngũ ZoPanel về việc chuyển từ cPanel, DirectAdmin, aaPanel và license cho doanh nghiệp.
Miễn phí 10 website · Không cần thẻ · Cài trong vài phút
Đọc tiếp

Checklist bảo mật vibe coding trước khi deploy app AI
Checklist bảo mật vibe coding cho app do AI viết: secret, phân quyền, truy cập database, thư viện, cấu hình deploy, cô lập server, giám sát và rollback.

Vibe coding là gì? Công cụ, giới hạn và cách đưa app lên mạng
Vibe coding là gì: nguồn gốc thuật ngữ, cách làm, các công cụ vibe coding phổ biến, làm tốt và dở ở đâu, và cách đưa app AI viết lên chạy thật cho khách dùng.

Deploy app Bolt.new, v0, Replit lên server riêng
Cách deploy app Bolt, v0, Replit lên server riêng: lấy code ra, sửa những gì hỏng khi rời công cụ, rồi gắn tên miền, SSL và tự deploy khi push.