Control panel cho thời đại AI: vibe code xong, push lên GitHub là chạy.Khám phá →

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.

Ảnh bìa blog ZoPanel: Dùng Claude Code, Cursor deploy lên server an toàn

Ý 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.md củ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.md mà không có CLAUDE.md, Claude Code sẽ đọc AGENTS.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:

  1. Cho agent làm trên một nhánh feature (git switch -c deploy-prep).
  2. 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.
  3. Chạy thử trên máy với PORT=4000 npm start và curl -i http://127.0.0.1:4000/healthz.
  4. 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.