Apidog Self-hosted Runner có thể được hiểu là một chương trình tự động có thể được lưu trữ trên một máy chủ độc lập. Chương trình này có thể thực thi các tác vụ trong Apidog, chẳng hạn như kiểm thử tự động theo lịch, nhập tài liệu API theo lịch và trả về kết quả phản hồi mock.Chuẩn bị#
Máy chủ lưu trữ (máy chủ hoặc PC cục bộ) phải được cài đặt Docker. Phiên bản Docker tối thiểu bắt buộc là 20.10.0, khuyến nghị sử dụng phiên bản 20.10.13.
Bắt đầu nhanh#
Phần này sẽ hướng dẫn bạn cách triển khai General Runner trên máy chủ của mình.1. Triển khai General Runner#
Điều hướng đến trang Apidog Home, chọn nhóm mong muốn, sau đó nhấp vào Resources ở bên phải. Từ đó, nhấp vào Deploy General Runner để bắt đầu.2. Lấy lệnh triển khai Runner#
Sau khi nhấp vào Deploy General Runner, hãy sao chép lệnh triển khai cho General Runner từ cửa sổ bật lên. Bạn có thể tùy chỉnh lệnh khi cần, hỗ trợ hệ điều hành máy chủ tùy chỉnh, cổng được phơi bày, thư mục dữ liệu được mount, v.v. Dưới đây là phần giải thích chi tiết về các thiết lập này:Server OS: Chỉ định hệ điều hành cho Docker container. Bao gồm Linux, macOS và Windows. Việc chọn đúng hệ điều hành là rất quan trọng để đảm bảo Docker container hoạt động đúng cách.
Docker Image: Có ba phiên bản: General, Slim và Custom. Nếu "custom script" của bạn cần gọi các chương trình bên ngoài, hãy chọn image phù hợp để cài đặt dựa trên môi trường bắt buộc:General: Chứa tất cả tính năng của Runner và được cài đặt sẵn các môi trường ngôn ngữ sau: Node.js 18, Java 21, Python 3 và PHP 8.
Slim: Chứa tất cả tính năng của Runner nhưng chỉ cài đặt sẵn Node.js 18.
Custom: Chứa tất cả tính năng của Runner và hỗ trợ môi trường ngôn ngữ tùy chỉnh cho các chương trình bên ngoài. Bạn có thể tạo Dockerfile của riêng mình để thêm hoặc xóa môi trường khi cần.
Exposed Port: Theo mặc định, Docker container không phơi bày các cổng nội bộ để truy cập từ bên ngoài. Sử dụng tham số -p, bạn có thể ánh xạ một cổng nội bộ của container tới một cổng trên máy chủ lưu trữ, cho phép truy cập từ bên ngoài vào các dịch vụ do container cung cấp. Ví dụ, -p 80:4524 ánh xạ cổng nội bộ 4524 của container tới cổng 80 trên máy chủ lưu trữ.
Mount Data Directory: Tham số -v cho phép bạn mount các thư mục từ máy chủ lưu trữ vào container, cho phép container truy cập và thao tác với các tệp trên máy chủ lưu trữ (ví dụ: cấu hình cơ sở dữ liệu hoặc chương trình bên ngoài). Ví dụ, -v "/opt/runner":/opt/runner mount thư mục /opt/runner của máy chủ lưu trữ vào thư mục /opt/runner của container.
Lệnh triển khai chứa thông tin token và sẽ chỉ được hiển thị một lần vì lý do bảo mật dữ liệu. Một lệnh mới sẽ được tạo mỗi khi bạn nhấp vào Deploy General Runner.Vui lòng lưu lệnh cục bộ, vì bạn có thể sử dụng lệnh này cho các lần nâng cấp Runner trong tương lai.
3. Triển khai Runner trên máy chủ#
Dán lệnh triển khai đã sao chép vào terminal của máy chủ, và quá trình cài đặt Runner sẽ tự động bắt đầu.Bạn có thể sửa đổi các thuộc tính triển khai của Runner thông qua biến môi trường để phù hợp hơn với các kịch bản sử dụng thực tế của mình. Đọc môi trường triển khai runner để biết thêm thông tin. 4. Xem trạng thái Runner trên máy chủ#
Bạn có thể xem trạng thái chạy của container thông qua Docker client.Bạn cũng có thể sử dụng lệnh docker ps trong terminal để xem trạng thái chạy của container.5. Xem General Runner đã triển khai tại Apidog#
Sau khi xác nhận rằng Runner container trên máy chủ đã được triển khai và bật, hãy quay lại Apidog. Bạn có thể thấy Runner đã được triển khai và kết nối với Apidog trong Team Resources → General Runner.Nếu General Runner đã được triển khai thành công trên máy chủ nhưng không hiển thị trong Apidog client, vui lòng nhấp vào nút làm mới ở phía bên phải của "General Runner" để làm mới trang và kiểm tra lại.
| Trạng thái | Mô tả |
|---|
| Đã khởi động | Runner được bật bình thường trong container trên máy chủ, duy trì liên lạc với Apidog và có thể xử lý các tác vụ liên quan do Apidog phát hành. |
| Đã dừng | Runner được dừng thủ công trong Apidog nhưng vẫn tiếp tục chạy bình thường trong container trên máy chủ và duy trì liên lạc. Runner sẽ không xử lý các tác vụ do Apidog phát hành, và các tác vụ mới không thể chỉ định một Runner đã dừng để thực thi. Bạn có thể bật thủ công Runner tại Apidog để khôi phục Runner về trạng thái đã khởi động. |
| Ngoại tuyến | Runner bị ngắt kết nối khỏi Apidog và không thể xử lý tác vụ. Điều này có thể do Runner container dừng trên máy chủ hoặc do sự cố liên lạc giữa máy chủ và Apidog. Để khôi phục Runner, hãy đảm bảo Runner container đang chạy và không có vấn đề liên lạc với Apidog, cho phép Runner khôi phục về trạng thái đã khởi động. |
Bạn có thể triển khai nhiều General Runner trong một nhóm. Khi tạo các tác vụ yêu cầu Self-hosted Runner, các thành viên trong nhóm có thể chọn từ các Runner khả dụng.Lưu tệp trong Runner#
Khi sử dụng Runner để thực thi các tác vụ như yêu cầu endpoint, kịch bản kiểm thử và tác vụ theo lịch, một số tệp cục bộ có thể cần thiết để hỗ trợ thực thi tác vụ. Ví dụ bao gồm:Gọi các ngôn ngữ lập trình khác trong custom script
Sử dụng kết nối cơ sở dữ liệu trong Pre/Post Processors
Sử dụng chứng chỉ SSL khi gửi yêu cầu
| Nội dung sử dụng | Đường dẫn thư mục được chỉ định (hoặc tên tệp) | Lệnh Docker ví dụ |
|---|
| Các ngôn ngữ lập trình khác | /app/external-programs/ | -v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms |
| Tệp cấu hình kết nối cơ sở dữ liệu | /app/database/database-connections.json | -v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json |
| Tệp danh sách chứng chỉ SSL | /app/ssl/ssl-client-cert-list.json | -v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json |
Bạn có thể tham khảo Trang này để xem cách xuất tệp cấu hình từ Apidog client. Nâng cấp và triển khai lại Runner#
Nâng cấp Runner#
Khi một phiên bản mới của Runner được phát hành, một biểu tượng nâng cấp sẽ xuất hiện trong giao diện người dùng Runner trên máy tính. Nhấp vào biểu tượng để cài đặt phiên bản mới nhất do Apidog cung cấp.Nhấp vào Upgrade sẽ nhắc bạn dừng Runner container hiện đang chạy. Xin lưu ý rằng sau khi container bị dừng, các tác vụ theo lịch và mọi tác vụ được gửi tới Runner này từ client sẽ không còn được thực thi.Sau khi bạn xác nhận nâng cấp, Apidog sẽ tự động dừng Runner container hiện tại và cung cấp một lệnh để triển khai phiên bản mới. Thực hiện theo các bước triển khai ban đầu để triển khai lại Runner. Sau khi triển khai thành công, bạn sẽ sử dụng phiên bản mới nhất. Lưu ý: Các tác vụ theo lịch hiện có trong client sẽ không bị ảnh hưởng và không cần được chỉ định lại.Triển khai lại Runner#
Nếu Runner gặp sự cố và bạn không thể tìm thấy cách giải quyết trong phần Hỏi & Đáp, hoặc hướng dẫn không hữu ích, hãy cân nhắc triển khai lại Runner. Để thực hiện việc này, hãy điều hướng đến mục More Actions của Runner cụ thể và nhấp vào Redeploy.Quy trình triển khai lại giống như nâng cấp ở trên. Lưu ý: Việc triển khai lại cũng sẽ dừng Runner container.Hỏi & Đáp#
Sử dụng lệnh docker ps để xác định Runner có vấn đề.
Sử dụng các lệnh sau để xem nhật ký:
Bước 1: Thu thập thông tin để chẩn đoán sự cố:
Tìm các mẫu lỗi hoặc chi tiết vận hành
Mở công cụ dành cho nhà phát triển (Alt+7+8), gửi một kịch bản kiểm thử đến Runner có vấn đề và ghi lại chi tiết endpoint
Xem lại nhật ký Runner để tìm bất kỳ thông báo lỗi hoặc manh mối nào
Nếu bạn có thể xác định vấn đề và vấn đề đó không do lỗi của Apidog gây ra, hãy tự khắc phục
Nếu bạn không thể xác định chính xác sự cố, hãy liên hệ với cộng đồng Apidog để được hỗ trợ thêm
Bước 1: Xác minh việc hoàn tất tác vụ:
Kiểm tra xem báo cáo kiểm thử cho tác vụ theo lịch có khả dụng trong Apidog client hay không
Xem lại nhật ký Runner để tìm bất kỳ sự cố nào
Đảm bảo các thiết lập thông báo được lưu trong tác vụ theo lịch
Kiểm tra kỹ rằng các điều kiện và người nhận được cấu hình chính xác
Thử kích hoạt tác vụ theo cách thủ công để xác nhận xem thông báo có được gửi đúng cách hay không
Có hai nguyên nhân có thể gây ra lỗi này:
Lệnh triển khai đã được tạo lại: Nếu bạn đã tạo lệnh, đóng cửa sổ bật lên, rồi nhấp lại, một token mới có thể làm token trước đó mất hiệu lực. Để khắc phục:Chuyển sang một nhóm khác ở góc trên bên trái, sau đó quay lại nhóm cần triển khai Runner
Tạo lại lệnh triển khai, sao chép và chạy lệnh đó. Đảm bảo bạn không nhấp để tạo lại lần nữa cho đến khi quy trình hoàn tất.
Lỗi dữ liệu ID với biến teamId: Đây là một lỗi đã bi ết và đã được khắc phục trong phiên bản mới nhất. Nếu sự cố vẫn tiếp diễn:Chuyển sang một nhóm khác ở góc trên bên trái, sau đó quay lại nhóm cần triển khai Runner
Tạo lại lệnh triển khai, sao chép và chạy lệnh đó. Đảm bảo bạn không nhấp để tạo lại lần nữa cho đến khi quy trình hoàn tất.
