Cách triển khai Mock Server tự lưu trữ trên mạng nội bộ với Apidog

Một số nhóm không thể gửi lưu lượng truy cập của họ lên đám mây. Có thể bạn đang ở sau tường lửa của công ty chặn các cuộc gọi ra ngoài đến các dịch vụ bên thứ ba. Có thể một quy tắc tuân thủ yêu cầu dữ liệu yêu cầu và phản hồi phải nằm trên các máy mà bạn kiểm soát. Hoặc có thể toàn bộ môi trường bị cách ly hoàn toàn và không có gì rời khỏi mạng nội bộ. Trong bất kỳ trường hợp nào trong số đó, một URL mock được lưu trữ trên cơ sở hạ tầng của người khác là điều không thể thực hiện, ngay cả khi dữ liệu mock đó là giả. Apidog giải quyết vấn đề này bằng một trình chạy tự lưu trữ (self-hosted runner). Thay vì các yêu cầu của bạn đi đến mock đám mây của Apidog, bạn triển khai một chương trình nhỏ trên một máy chủ thuộc sở hữu của mình và chương trình đó sẽ trả về các phản hồi mock từ bên trong mạng của bạn. Thiết kế vẫn nằm trong dự án Apidog của bạn như mọi khi; chỉ có việc phục vụ dữ liệu là được chuyển sang phần cứng của bạn. Hướng dẫn này sẽ giải thích trình chạy là gì, khi nào nên chọn nó thay vì mock đám mây, cách thiết lập nó từ tài liệu và một điểm khác biệt khiến mọi người bối rối: trình chạy không phải là CLI. Nếu bạn muốn có cái nhìn tổng quan hơn về lý do các nhóm chạy mock trên máy chủ của riêng họ, hướng dẫn về máy chủ mock API tự lưu trữ bao gồm trường hợp chung, và Sáng kiến OpenAPI giải thích đặc tả mà các mock này được tạo ra. Muốn làm theo? Hãy tải Apidog trước.nút

Trình chạy tự lưu trữ là gì

Apidog Self-hosted Runner là một chương trình tự động mà bạn lưu trữ trên một máy chủ độc lập. Nó được chính thức gọi là General Runner, và nó thực hiện ba công việc: chạy các kiểm thử tự động theo lịch trình, nhập tài liệu API và trả về các phản hồi mock. Công việc thứ ba đó là điều mà bài viết này đề cập.

Đây là ý tưởng chính. Sau khi bạn triển khai General Runner và đặt Server Host cho nó, một môi trường mới có tên Runner Mock sẽ tự động xuất hiện trong dự án của bạn. Bất kỳ yêu cầu nào bạn gửi thông qua môi trường đó sẽ nhận được phản hồi mock từ trình chạy tự lưu trữ của bạn thay vì từ mock đám mây của Apidog. Cùng một thiết kế mock, cùng một dữ liệu được tạo, nhưng được phục vụ bởi một máy khác. Lưu lượng truy cập của bạn không bao giờ rời khỏi mạng của bạn.

Đây là lựa chọn tự lưu trữ thay thế cho mock đám mây. Nếu nhóm của bạn có thể truy cập internet và không có quy tắc nào cấm, mock đám mây của Apidog đơn giản hơn vì không cần triển khai gì cả. Hãy sử dụng trình chạy khi một trong các trường hợp sau đúng:

• Lưu lượng truy cập đi ra các máy chủ bên ngoài bị chặn hoặc bị kiểm tra nghiêm ngặt.
• Một chính sách tuân thủ yêu cầu dữ liệu yêu cầu phải nằm trên cơ sở hạ tầng nội bộ.
• Môi trường bị cách ly và hoàn toàn không thể truy cập một điểm cuối đám mây.
• Bạn muốn đo độ trễ của mock trên mạng LAN của mình, chứ không phải qua internet công cộng.

Nếu không có trường hợp nào ở trên áp dụng, thì việc có thêm máy chủ Docker sẽ là một chi phí phát sinh không cần thiết. Hãy thành thật với bản thân về trường hợp bạn đang gặp phải trước khi cung cấp một máy chủ.

Một lưu ý về gói và quyền. Tài liệu của Apidog không nêu rõ ranh giới giữa bản miễn phí và trả phí cho General Runner hoặc cho mock tự lưu trữ, và chúng không liệt kê bất kỳ số liệu giá nào cho nó, vì vậy hướng dẫn này sẽ không đưa ra bất kỳ thông tin nào. Điều mà việc thiết lập yêu cầu là quyền quản trị viên nhóm hoặc dự án, vì việc triển khai trình chạy diễn ra trong Team Resources, và chỉ quản trị viên mới có thể mở các cài đặt đó. Nếu bạn không thấy bảng Resources, đó là lý do.

Những gì bạn cần trước khi bắt đầu

Trình chạy được cung cấp dưới dạng vùng chứa Docker, vì vậy máy chủ lưu trữ nó cần cài đặt Docker. Tài liệu yêu cầu phiên bản tối thiểu là 20.10.0, và khuyến nghị 20.10.13 trở lên. Kiểm tra phiên bản bạn có:

docker --version

Bạn cũng cần một nơi để chạy nó: một máy Linux, macOS hoặc Windows mà cả các máy khách Apidog của nhóm bạn và dịch vụ Apidog đều có thể truy cập. Trên mạng nội bộ, điều đó thường có nghĩa là một máy chủ nội bộ với địa chỉ IP hoặc tên máy chủ ổn định. Đó là danh sách tất cả các điều kiện tiên quyết: Docker, một máy chủ và quyền quản trị trên nhóm. Mọi thứ khác bạn cấu hình bên trong Apidog.

Triển khai General Runner

Lệnh triển khai được tạo tự động cho bạn từ bên trong Apidog và nó mang theo một mã thông báo, vì vậy bạn không cần phải tự viết tay. Đây là quy trình.

Tạo lệnh

Mở Apidog Home, chọn nhóm của bạn, sau đó nhấp vào Resources ở thanh bên phải và chọn Deploy General Runner. Một cửa sổ bật lên sẽ xuất hiện nơi bạn thiết lập một vài thứ:

• Server OS: Linux, macOS hoặc Windows, để lệnh được tạo khớp với máy chủ của bạn.
• Docker Image: chọn General, Slim hoặc Custom. General được cài đặt sẵn Node.js 18, Java 21, Python 3 và PHP 8. Slim chỉ có Node.js 18, cho một ảnh nhỏ hơn. Custom cho phép bạn cung cấp Dockerfile của riêng mình khi bạn cần các môi trường chạy bổ sung cho các tập lệnh kiểm thử.
• Exposed Port: được đặt bằng tham số -p, ví dụ -p 80:4524, ánh xạ cổng 80 của máy chủ tới cổng nội bộ của trình chạy.
• Mounted Data Directory: được đặt bằng tham số -v, để dữ liệu của trình chạy vẫn tồn tại trên máy chủ qua các lần khởi động lại.

Khi hoàn tất, hãy sao chép lệnh đã tạo. Điều này quan trọng: lệnh chỉ được hiển thị một lần, vì lý do bảo mật dữ liệu, bởi vì nó nhúng mã thông báo của bạn. Nếu bạn làm mất nó, bạn sẽ tạo một mã mới thay vì khôi phục mã cũ. Hãy nắm bắt nó ngay lập tức.

Chạy nó trên máy chủ

Dán lệnh vào terminal của máy chủ của bạn. Quá trình cài đặt tự động bắt đầu và kéo ảnh. Một lệnh hoàn chỉnh trông đại khái như thế này (lệnh của bạn sẽ khác, và sẽ bao gồm mã thông báo thực):

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>

Xác nhận vùng chứa đang chạy:

docker ps

Bạn sẽ thấy vùng chứa của trình chạy được liệt kê cùng với ánh xạ cổng của nó. Một ứng dụng Docker client như Docker Desktop hiển thị điều tương tự nếu bạn muốn xem giao diện người dùng.

Xác nhận nó đã được đăng ký

Trở lại Apidog, vào Team Resources và mở General Runner. Nhấp vào nút làm mới. Trình chạy bây giờ sẽ hiển thị là đã triển khai với trạng thái Started. Nếu nó không xuất hiện ngay lập tức, nút làm mới là cách khắc phục của bạn; hãy đợi một chút và nhấp lại.

Trạng thái của trình chạy có ba trạng thái đáng chú ý:

• Started: đã bật, đang kết nối với Apidog, đang xử lý các tác vụ. Đây là trạng thái bạn mong muốn.
• Stopped: ai đó đã dừng nó thủ công trong Apidog. Nó vẫn được triển khai nhưng sẽ không xử lý các tác vụ.
• Offline: nó đã mất kết nối với Apidog, vì vậy nó không thể xử lý bất cứ điều gì. Kiểm tra vùng chứa và đường dẫn mạng.

Bật Runner Mock

Triển khai trình chạy cung cấp cho bạn tác nhân. Thêm một bước nữa sẽ hướng lưu lượng mock của bạn tới nó.

Trong Team Resources, mở General Runner và tìm trường Server Host. Nhập địa chỉ mà trình chạy của bạn có thể truy cập được. Đối với một thiết lập HTTP thông thường, đó là máy chủ và cổng bạn đã mở, ví dụ http://127.0.0.1:80 cho một kiểm thử cục bộ hoặc http://runner.internal.example.com:80 cho một máy chủ mạng nội bộ chia sẻ. Đằng sau một proxy chấm dứt TLS, nó trông giống như https://runner.example.com:443. Sẽ có thêm chi tiết về HTTPS sau đây.

Sau khi Server Host được đặt, Apidog tự động kết nối môi trường Runner Mock cho dự án của bạn. Xác minh nó: mở dự án, vào Environment Management, và xác nhận Runner Mock hiện đã hiển thị trong danh sách môi trường. Bạn không tự tạo nó; việc đặt Server Host là điều đã làm cho nó xuất hiện.

Gửi yêu cầu thông qua mock tự lưu trữ

Bây giờ hãy sử dụng nó. Giả sử bạn có một điểm cuối GET /orders/{orderId} trong một dự án cho API quản lý đơn hàng nội bộ. Mở điểm cuối đó, sau đó trong danh sách thả xuống môi trường ở trên cùng, chọn Runner Mock thay vì môi trường đám mây. Gửi yêu cầu.

Phản hồi sẽ trả về từ trình chạy của bạn. Vì Apidog tạo dữ liệu mock từ lược đồ của bạn, một lược đồ Order được định nghĩa rõ ràng sẽ trả về các giá trị thực tế thay vì các trình giữ chỗ trống:

curl http://runner.internal.example.com:80/orders/10583

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}

JSON đó không bao giờ chạm vào internet công cộng. Trình chạy đã xây dựng nó từ lược đồ của điểm cuối của bạn và phục vụ nó từ bên trong mạng của bạn. Việc tạo dữ liệu theo trường như giá trị customerEmail ở trên đến từ việc Apidog đọc các loại và tên trường trong lược đồ của bạn, cùng một công cụ được đề cập trong bài viết liên quan về tự động tạo dữ liệu mock thực tế với mock thông minh. Nếu bạn muốn kiểm soát chính xác những gì một yêu cầu cụ thể trả về, bạn thêm một kỳ vọng mock trên điểm cuối, và trình chạy sẽ phục vụ kỳ vọng đó theo cách mà mock đám mây sẽ làm. Cơ chế xây dựng các phản hồi mock tốt là như nhau cho dù máy chủ là của Apidog hay của bạn; chỉ có máy chủ là thay đổi. Các khái niệm chung đằng sau tạo mock API vẫn không thay đổi.

HTTPS, gắn dữ liệu và các chi tiết thực tế khác

Một chạy thử nghiệm trên http://127.0.0.1 thì dễ. Một triển khai mạng nội bộ chia sẻ có một vài điểm khó khăn đáng biết trước khi bạn triển khai nó cho một nhóm.

HTTPS cần một reverse proxy

Trình chạy không có hỗ trợ chứng chỉ HTTPS tích hợp và không thực hiện việc cấp chứng chỉ tự động. Nó sẽ không tìm nạp hoặc quản lý chứng chỉ TLS cho bạn. Nếu bạn cần https://, hãy chấm dứt TLS tại một reverse proxy phía trước trình chạy, ví dụ như Nginx giữ chứng chỉ của bạn, sau đó trỏ Server Host tới URL HTTPS của proxy. Nếu không có proxy, hãy sử dụng http://host:port. Đừng đặt Server Host thành https:// và mong đợi trình chạy tự trả lời TLS trực tiếp; nó không thể.

Một khối Nginx tối thiểu đứng trước một trình chạy trên cổng 4524 trông như thế này:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}

Khi đó Server Host trở thành https://runner.example.com:443. Hướng dẫn MDN về HTTPS là một tài liệu ôn tập tốt nếu việc chấm dứt TLS còn mới mẻ đối với nhóm của bạn.

Gắn tệp theo đường dẫn cụ thể

Nếu các mock hoặc kiểm thử của bạn cần các tệp bổ sung, trình chạy mong đợi chúng ở các đường dẫn cố định bên trong vùng chứa, vì vậy hãy gắn chúng ở đó:

• Các chương trình bên ngoài nằm trong /app/external-programs/.
• Cấu hình kết nối cơ sở dữ liệu nằm trong /app/database/database-connections.json.
• Chứng chỉ máy khách SSL nằm trong /app/ssl/ssl-client-cert-list.json.

Hãy kết nối chúng thông qua các điểm gắn -v của bạn để chúng tồn tại qua các lần khởi động lại.

Hành vi triển khai lại và nâng cấp

Khi một phiên bản trình chạy mới được phát hành, bạn sẽ thấy tùy chọn Upgrade (Nâng cấp), và dưới More Actions (Thêm hành động) bạn có thể Redeploy (Triển khai lại). Cả hai hành động này đều dừng vùng chứa đang chạy trong khi vùng chứa mới khởi động. Điều đáng an tâm là: các tác vụ theo lịch trình hiện có trong máy khách Apidog không bị ảnh hưởng bởi việc triển khai lại hoặc nâng cấp, vì vậy bạn chỉ làm gián đoạn việc phục vụ trực tiếp trong khoảnh khắc vùng chứa khởi động lại, chứ không mất cấu hình.

Tự động hóa quy trình làm việc với Apidog CLI

Đây là điểm khác biệt giúp tránh nhầm lẫn: trình chạy là một tác nhân tồn tại lâu dài có thể phục vụ mock và chạy các tác vụ theo lịch trình, trong khi Apidog CLI là một trình chạy kiểm thử một lần cho CI. Chúng là những công cụ khác nhau. CLI không thể phục vụ, khởi động hoặc lưu trữ một máy chủ mock. Không có apidog run mock và không có apidog mock serve. Lệnh apidog run của CLI thực thi các kịch bản kiểm thử, thư mục kịch bản kiểm thử và bộ kiểm thử, và nhóm lệnh mock của nó chỉ thực hiện CRUD trên các mong đợi mock dưới dạng dữ liệu. Việc phục vụ mock là công việc của trình chạy, không bao giờ là của CLI.

Vì vậy, hai thứ này khớp với nhau như sau. CLI và các tác nhân mã hóa AI như Cursor, Claude Code và Codex có thể tạo và cập nhật các điểm cuối và lược đồ trong dự án của bạn, giúp giữ cho đầu ra mock của bạn chính xác khi đặc tả phát triển. Sau khi mock tự lưu trữ đã mở khóa công việc frontend, các kịch bản kiểm thử của cùng dự án sẽ chạy không giao diện trong CI chỉ với một lệnh duy nhất, xác thực backend thực tế dựa trên chính hợp đồng mà mock đã mô tả:

apidog run -t <scenario_id> -e <env_id> -r html,cli

Lệnh đó sẽ chạy các kịch bản của bạn đối với backend trực tiếp và ghi báo cáo HTML và CLI. Cài đặt là npm install -g apidog-cli trên Node.js v16 trở lên; hướng dẫn cài đặt Apidog CLI bao gồm apidog login và thiết lập mã thông báo. Để chạy kiểm thử đó diễn ra trên mỗi lần push, hãy tích hợp nó vào quy trình của bạn với hướng dẫn CI/CD của Apidog CLI. Bài viết về tạo mock API từ CLI giải thích chính xác lý do tại sao terminal quản lý định nghĩa mock nhưng không lưu trữ chúng.

Câu hỏi thường gặp

Tôi có cần trình chạy tự lưu trữ nếu nhóm của tôi có thể truy cập internet không?

Có lẽ là không. Mock đám mây không cần triển khai gì và là con đường đơn giản hơn. Hãy chọn trình chạy khi lưu lượng truy cập đi ra bị chặn hoặc kiểm tra, một quy tắc tuân thủ giữ dữ liệu trên cơ sở hạ tầng nội bộ hoặc môi trường bị cách ly. Nếu bạn đang so sánh phương pháp lưu trữ với phương pháp được quản lý trước, thì hướng dẫn chi tiết về Apidog cloud mock là phần bổ trợ tự nhiên cho hướng dẫn này.

Apidog CLI có thể khởi động một máy chủ mock tự lưu trữ không?

Không. CLI chạy các kiểm thử với apidog run và quản lý các mong đợi mock dưới dạng dữ liệu với nhóm lệnh mock của nó. Việc phục vụ lưu lượng mock được thực hiện bởi General Runner hoặc bởi mock đám mây, không bao giờ bởi CLI. Nếu bạn hy vọng gõ một lệnh terminal và có một mock đang chạy trên một cổng, đó là công việc của trình chạy, được thiết lập thông qua GUI như mô tả ở trên.

Trình chạy có tự hỗ trợ HTTPS không?

Nó không cung cấp chứng chỉ hoặc tự động cấp phát chúng. Hãy đặt một reverse proxy như Nginx ở phía trước để chấm dứt TLS, sau đó trỏ Server Host tới URL https:// của proxy. Nếu không có proxy, hãy sử dụng http://host:port.

Tại sao trình chạy của tôi không xuất hiện sau khi tôi chạy lệnh?

Mở Team Resources, vào General Runner, và nhấp vào nút làm mới. Việc đăng ký có thể mất một chút thời gian. Nếu nó vẫn không xuất hiện, hãy xác nhận vùng chứa đang chạy bằng docker ps và rằng máy chủ có thể truy cập được từ Apidog. Trạng thái Offline có nghĩa là kết nối đã bị mất; Started là trạng thái bạn mong muốn.

Nhiều nhóm có thể chia sẻ một trình chạy để phục vụ mock toàn cầu không?

Một trình chạy được đăng ký cho nhóm mà bạn đã triển khai nó, và môi trường Runner Mock của nó xuất hiện cho từng dự án. Nếu bạn điều hành các nhóm phân tán chia sẻ môi trường mock, các mẫu trong hướng dẫn về chia sẻ môi trường mock giữa các nhóm toàn cầu sẽ giúp bạn quyết định triển khai bao nhiêu trình chạy và ở đâu.

Tổng kết

Mocking tự lưu trữ với General Runner giúp giữ dữ liệu yêu cầu của bạn trên cơ sở hạ tầng mà bạn kiểm soát trong khi thiết kế mock của bạn vẫn ở đúng vị trí của nó, trong dự án Apidog của bạn. Bạn triển khai một vùng chứa Docker, đặt Server Host, và môi trường Runner Mock sẽ làm phần còn lại. Hãy sử dụng nó khi không thể truy cập đám mây, và tiếp tục sử dụng mock đám mây khi có thể. Sẵn sàng chạy mock trên mạng của riêng bạn? Tải xuống Apidog, triển khai một trình chạy và phục vụ phản hồi Runner Mock đầu tiên của bạn mà không có một gói dữ liệu nào rời khỏi mạng nội bộ của bạn.