DEV Community

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

Posted on • Originally published at apidog.com

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 lên đám mây: tường lửa chặn dịch vụ bên thứ ba, quy định tuân thủ yêu cầu dữ liệu nằm trên hạ tầng nội bộ, hoặc môi trường bị cô lập hoàn toàn. Trong các trường hợp này, URL mock được lưu trữ bên ngoài không phù hợp. Với self-hosted runner của Apidog, bạn triển khai một chương trình nhỏ trên máy chủ do mình kiểm soát để phục vụ phản hồi mock ngay trong mạng nội bộ. Thiết kế API và mock vẫn nằm trong dự án Apidog; chỉ lớp phục vụ phản hồi được chuyển sang hạ tầng của bạn. Để tìm hiểu thêm về mô hình chung, xem hướng dẫn về máy chủ mock API tự lưu trữ và Sáng kiến OpenAPI.

Dùng thử Apidog ngay hôm nay

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

Apidog Self-hosted Runner, còn gọi là General Runner, là chương trình bạn chạy trên một máy chủ độc lập. Runner có thể:

  1. Chạy kiểm thử tự động theo lịch.
  2. Nhập tài liệu API.
  3. Phục vụ phản hồi mock.

Bài viết này tập trung vào trường hợp thứ ba.

General Runner

Sau khi triển khai General Runner và cấu hình Server Host, Apidog tự tạo môi trường Runner Mock trong dự án. Khi chọn môi trường này, yêu cầu mock sẽ đi đến runner nội bộ thay vì mock đám mây của Apidog.

Bạn vẫn sử dụng cùng thiết kế API, schema và kỳ vọng mock. Điểm khác biệt duy nhất là phản hồi được tạo và trả về từ máy chủ của bạn.

Khi nào nên dùng self-hosted runner?

Mock đám mây của Apidog đơn giản hơn nếu nhóm có thể dùng internet và không bị giới hạn chính sách. Chỉ nên triển khai runner khi có ít nhất một điều kiện sau:

  • Lưu lượng ra ngoài đến máy chủ bên ngoài bị chặn hoặc bị kiểm soát nghiêm ngặt.
  • Chính sách tuân thủ yêu cầu dữ liệu request/response nằm trên hạ tầng nội bộ.
  • Môi trường air-gapped không thể truy cập endpoint đám mây.
  • Bạn cần đo độ trễ mock trong LAN thay vì qua internet công cộng.

Nếu không gặp các trường hợp này, việc vận hành thêm một Docker host thường là chi phí không cần thiết.

Bạn cần quyền quản trị nhóm hoặc dự án để triển khai runner, vì thao tác này nằm trong Team Resources. Nếu không thấy mục Resources, hãy kiểm tra quyền của tài khoản.

Điều kiện trước khi bắt đầu

General Runner được phân phối dưới dạng Docker container.

1. Kiểm tra Docker

Tài liệu yêu cầu Docker tối thiểu 20.10.0 và khuyến nghị 20.10.13 trở lên:

docker --version
Enter fullscreen mode Exit fullscreen mode

2. Chuẩn bị máy chủ

Bạn cần một máy Linux, macOS hoặc Windows mà:

  • Thành viên trong nhóm có thể truy cập.
  • Dịch vụ Apidog có thể kết nối đến.
  • Có IP hoặc hostname ổn định nếu dùng trong mạng nội bộ.

Ví dụ:

runner.internal.example.com
Enter fullscreen mode Exit fullscreen mode

Ngoài Docker, máy chủ và quyền quản trị, các cấu hình còn lại thực hiện trong Apidog.

Triển khai General Runner

Apidog tạo sẵn lệnh triển khai chứa token đăng ký runner. Không cần tự viết token hoặc lệnh Docker thủ công.

Bước 1: Tạo lệnh triển khai

Trong Apidog:

  1. Mở Home.
  2. Chọn nhóm.
  3. Mở Resources ở thanh bên phải.
  4. Chọn Deploy General Runner.

Trong cửa sổ triển khai, cấu hình các mục sau:

  • Server OS: Linux, macOS hoặc Windows.
  • Docker Image:
    • General: có sẵn Node.js 18, Java 21, Python 3 và PHP 8.
    • Slim: chỉ có Node.js 18, phù hợp khi cần image nhỏ hơn.
    • Custom: dùng Dockerfile riêng khi cần thêm runtime cho script kiểm thử.
  • Exposed Port: cấu hình qua -p, ví dụ -p 80:4524.
  • Mounted Data Directory: cấu hình qua -v để dữ liệu runner vẫn tồn tại sau khi container khởi động lại.

Sao chép lệnh ngay khi Apidog hiển thị. Lệnh chỉ xuất hiện một lần vì chứa token. Nếu mất token, bạn cần tạo token mới.

Bước 2: Chạy container trên máy chủ

Dán lệnh do Apidog tạo vào terminal của máy chủ. Một lệnh mẫu có dạng:

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

Lệnh thực tế của bạn sẽ có token riêng do Apidog sinh ra.

Kiểm tra container:

docker ps
Enter fullscreen mode Exit fullscreen mode

Bạn sẽ thấy container runner cùng port mapping đã cấu hình.

Bước 3: Xác nhận runner đã đăng ký

Quay lại Apidog:

  1. Mở Team Resources.
  2. Chọn General Runner.
  3. Nhấn nút làm mới.

Runner cần hiển thị trạng thái Started.

Các trạng thái quan trọng:

  • Started: runner đang chạy, kết nối với Apidog và xử lý tác vụ.
  • Stopped: runner đã bị dừng thủ công trong Apidog.
  • Offline: runner mất kết nối với Apidog; cần kiểm tra container và mạng.

Nếu runner chưa xuất hiện ngay, chờ một lúc rồi nhấn làm mới lại.

Bật Runner Mock

Triển khai runner chỉ tạo tác nhân chạy. Bạn vẫn cần đặt địa chỉ để Apidog gửi lưu lượng mock đến runner.

Trong Team Resources → General Runner, tìm trường Server Host và nhập URL có thể truy cập đến runner.

Ví dụ:

http://127.0.0.1:80
Enter fullscreen mode Exit fullscreen mode

Dùng cho kiểm thử cục bộ.

http://runner.internal.example.com:80
Enter fullscreen mode Exit fullscreen mode

Dùng cho máy chủ nội bộ dùng chung.

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Dùng khi runner đứng sau reverse proxy xử lý TLS.

Sau khi lưu Server Host, Apidog tự động tạo môi trường Runner Mock cho dự án.

Kiểm tra bằng cách:

  1. Mở dự án.
  2. Vào Environment Management.
  3. Xác nhận môi trường Runner Mock xuất hiện trong danh sách.

Bạn không cần tạo môi trường này thủ công.

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

Giả sử API quản lý đơn hàng có endpoint:

GET /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

Để gọi mock từ runner:

  1. Mở endpoint trong Apidog.
  2. Chọn môi trường Runner Mock ở menu môi trường.
  3. Gửi request.

Bạn cũng có thể gọi trực tiếp bằng curl:

curl http://runner.internal.example.com:80/orders/10583
Enter fullscreen mode Exit fullscreen mode

Ví dụ phản hồi:

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

Phản hồi này được tạo từ schema endpoint và được phục vụ trong mạng nội bộ. Dữ liệu không cần đi qua internet công cộng.

Để nhận mock thực tế hơn, hãy định nghĩa schema rõ ràng, bao gồm kiểu dữ liệu và tên trường. Ví dụ, Apidog có thể suy luận dữ liệu cho customerEmail dựa trên tên trường và kiểu schema. Xem thêm hướng dẫn tự động tạo dữ liệu mock thực tế với mock thông minh.

Khi cần kiểm soát chính xác phản hồi của một request, hãy thêm mock expectation vào endpoint. Runner sẽ phục vụ expectation đó tương tự mock đám mây. Các khái niệm về tạo mock API không thay đổi; chỉ vị trí máy chủ phục vụ thay đổi.

HTTPS, gắn dữ liệu và các chi tiết triển khai

HTTPS cần reverse proxy

Runner không có chức năng tích hợp để cấp hoặc quản lý chứng chỉ HTTPS. Nếu cần dùng https://, hãy đặt reverse proxy phía trước runner để chấm dứt TLS.

Ví dụ Nginx chuyển tiếp đến runner chạy ở cổng 4524:

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;
    }
}
Enter fullscreen mode Exit fullscreen mode

Sau đó đặt Server Host thành:

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Nếu không dùng reverse proxy, hãy cấu hình URL HTTP thông thường:

http://host:port
Enter fullscreen mode Exit fullscreen mode

Tham khảo thêm hướng dẫn HTTPS của MDN.

Gắn tệp vào container

Nếu mock hoặc kiểm thử cần tệp bổ sung, hãy mount chúng vào đúng đường dẫn mà runner yêu cầu:

Loại tệp Đường dẫn trong container
Chương trình bên ngoài /app/external-programs/
Cấu hình kết nối cơ sở dữ liệu /app/database/database-connections.json
Danh sách chứng chỉ SSL client /app/ssl/ssl-client-cert-list.json

Dùng -v trong lệnh Docker để mount các tệp hoặc thư mục này. Việc đó giúp dữ liệu tồn tại sau khi container được khởi động lại.

Triển khai lại và nâng cấp

Khi có phiên bản runner mới, Apidog cung cấp các tùy chọn:

  • Upgrade
  • More Actions → Redeploy

Cả hai thao tác đều dừng container hiện tại trong lúc container mới khởi động. Các tác vụ theo lịch đã cấu hình trong Apidog không bị mất; chỉ việc phục vụ trực tiếp bị gián đoạn ngắn trong quá trình restart.

Tự động hóa kiểm thử với Apidog CLI

Đừng nhầm General Runner với Apidog CLI:

Công cụ Mục đích
General Runner Tồn tại lâu dài, phục vụ mock và chạy tác vụ theo lịch
Apidog CLI Chạy kiểm thử một lần trong terminal hoặc CI

CLI không thể khởi động hoặc lưu trữ mock server. Không có các lệnh như:

apidog run mock
Enter fullscreen mode Exit fullscreen mode

hoặc:

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

Lệnh apidog run dùng để chạy kịch bản kiểm thử, thư mục kiểm thử hoặc test suite. Nhóm lệnh mock của CLI chỉ quản lý mock expectation dưới dạng dữ liệu.

Sau khi Runner Mock giúp frontend bắt đầu phát triển mà không cần backend thật, bạn có thể chạy kiểm thử hợp đồng trong CI với backend thực:

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Lệnh này chạy scenario với môi trường đã chọn và xuất báo cáo HTML lẫn CLI.

Cài đặt CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

CLI yêu cầu Node.js v16 trở lên. Xem hướng dẫn cài đặt Apidog CLI để thiết lập apidog login và token.

Để chạy kiểm thử theo mỗi lần push, tích hợp lệnh này vào pipeline theo 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 vì sao CLI quản lý định nghĩa mock nhưng không trực tiếp phục vụ mock.

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

Tôi có cần self-hosted runner nếu nhóm có internet không?

Thông thường là không. Mock đám mây không yêu cầu triển khai và đơn giản hơn để vận hành. Hãy dùng self-hosted runner khi lưu lượng ra ngoài bị chặn, bị kiểm tra, bị giới hạn bởi chính sách tuân thủ hoặc môi trường bị cô lập.

Nếu đang đánh giá mock được quản lý trước, xem thêm hướng dẫn Apidog cloud mock.

Apidog CLI có thể khởi động mock server tự lưu trữ không?

Không. CLI chạy kiểm thử bằng apidog run và quản lý mock expectation bằng nhóm lệnh mock. Việc phục vụ lưu lượng mock do General Runner hoặc mock đám mây đảm nhiệm.

Runner có tự hỗ trợ HTTPS không?

Không. Runner không tự cấp hoặc quản lý chứng chỉ TLS. Hãy dùng reverse proxy như Nginx để chấm dứt TLS, sau đó cấu hình Server Host bằng URL https:// của proxy.

Vì sao runner không xuất hiện sau khi chạy lệnh?

Thử theo thứ tự sau:

  1. Mở Team Resources → General Runner.
  2. Nhấn làm mới.
  3. Kiểm tra container: 
   docker ps
Enter fullscreen mode Exit fullscreen mode
  1. Kiểm tra máy chủ và đường dẫn mạng có thể kết nối đến Apidog.

Trạng thái Offline cho biết runner đã mất kết nối; Started là trạng thái mong muốn.

Nhiều nhóm có thể dùng chung một runner không?

Runner được đăng ký cho nhóm đã triển khai nó, và môi trường Runner Mock xuất hiện trong từng dự án của nhóm đó. Nếu cần chia sẻ môi trường mock giữa nhiều nhóm hoặc khu vực, xem hướng dẫn chia sẻ môi trường mock giữa các nhóm toàn cầu.

Tổng kết

Self-hosted mocking với General Runner giữ request và response mock trên hạ tầng do bạn kiểm soát, trong khi thiết kế API vẫn được quản lý trong dự án Apidog.

Quy trình triển khai gồm:

  1. Cài Docker trên máy chủ.
  2. Triển khai General Runner từ Team Resources.
  3. Cấu hình Server Host.
  4. Chọn môi trường Runner Mock trong dự án.
  5. Gửi request mock qua máy chủ nội bộ.

Dùng runner khi không thể hoặc không nên truy cập mock đám mây. Nếu không có ràng buộc mạng hoặc tuân thủ, mock đám mây vẫn là lựa chọn đơn giản hơn.

Sẵn sàng chạy mock trong mạng riêng? Tải xuống Apidog, triển khai runner và phục vụ phản hồi Runner Mock đầu tiên mà không đưa dữ liệu ra khỏi mạng nội bộ.

Top comments (0)