Hướng dẫn 16: Triển khai Docker

Chào mừng các nhà thám hiểm Hermes đã quay trở lại! Trong bài hướng dẫn trước, chúng ta đã làm quen với việc chạy Hermes Agent trực tiếp trên máy của mình. Hôm nay, chúng ta sẽ nâng cấp lên một tầm cao mới: đưa Hermes vào bên trong một container Docker. Đây là một bước ngoặt lớn giúp giữ cho môi trường cài đặt của bạn sạch sẽ, dễ di chuyển và dễ dàng nâng cấp.

Hai cách Docker kết hợp với Hermes

Trước khi đi sâu vào, điều quan trọng là phải hiểu rằng Docker và Hermes Agent có thể hoạt động cùng nhau theo hai cách riêng biệt:

Chạy Hermes trong Docker – Bản thân agent sống bên trong một container. Đây là điều chúng ta sẽ tập trung vào hôm nay.
Docker như một backend terminal – Hermes chạy trên máy chủ của bạn, nhưng mọi lệnh nó thực thi đều diễn ra bên trong một sandbox Docker liên tục. Điều này rất tuyệt cho bảo mật và cô lập, nhưng đó là chủ đề cho một ngày khác.

Hôm nay, chúng ta tập trung vào lựa chọn 1. Vẻ đẹp của cách tiếp cận này là tất cả dữ liệu của bạn—cấu hình, khóa API, phiên làm việc, kỹ năng và ký ức—nằm trong một thư mục duy nhất trên máy chủ của bạn, được gắn vào container tại /opt/data. Bản thân container không lưu trạng thái, vì vậy bạn có thể kéo phiên bản mới và nâng cấp mà không mất bất cứ thứ gì.

Bắt đầu nhanh: Container đầu tiên của bạn

Nếu bạn hoàn toàn mới với Hermes, cách dễ nhất là tạo một thư mục dữ liệu và chạy trình hướng dẫn cài đặt một cách tương tác. Trình hướng dẫn sẽ hướng dẫn bạn nhập khóa API và lưu chúng vào ~/.hermes/.env.

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Một lời cảnh báo: tránh sử dụng bảng điều khiển VPS dựa trên trình duyệt (như của Hetzner Cloud) cho các lệnh này. Chúng thường làm hỏng các ký tự đặc biệt như :, @ và =, có thể âm thầm làm hỏng các tham số docker run của bạn. Luôn kết nối qua SSH (ssh root@<host>) để nhập liệu an toàn khi sao chép-dán. Nếu bạn buộc phải dùng bảng điều khiển trình duyệt, hãy gõ lệnh thủ công và kiểm tra kỹ từng ký tự.

Khi đã vào trình hướng dẫn, bạn nên thiết lập một hệ thống trò chuyện (Telegram, Discord, v.v.) để gateway của bạn có nơi gửi tin nhắn.

Chạy ở chế độ Gateway

Sau khi cấu hình xong, bạn sẽ muốn chạy Hermes như một gateway nền liên tục. Đây là cách nó kết nối với các nền tảng trò chuyện của bạn và hoạt động 24/7.

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Cờ -p 8642:8642 mở máy chủ API tương thích OpenAI và endpoint kiểm tra sức khỏe của gateway. Nó là tùy chọn nếu bạn chỉ sử dụng các nền tảng trò chuyện, nhưng bắt buộc nếu bạn muốn dashboard hoặc các công cụ bên ngoài truy cập vào gateway của mình.

Đây là một tính năng mới thú vị: bên trong image Docker chính thức, gateway run hiện được giám sát tự động bởi s6-overlay. Điều này có nghĩa là nếu tiến trình gateway bị sập, nó sẽ được khởi động lại trong vài giây mà không làm mất container. Bạn sẽ thấy một dấu vết trong docker logs xác nhận bản nâng cấp. Nếu bạn muốn hành vi cũ (container thoát khi gateway thoát), hãy truyền --no-supervise hoặc đặt HERMES_GATEWAY_NO_SUPERVISE=1. Đối với môi trường sản xuất, chế độ giám sát mặc định tốt hơn hẳn.

Mở máy chủ API

Theo mặc định, máy chủ API bị chặn bởi API_SERVER_ENABLED=true. Để mở nó ra ngoài 127.0.0.1 bên trong container, bạn cần đặt một vài biến môi trường:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

API_SERVER_KEY phải có ít nhất 8 ký tự—hãy tạo một khóa bằng openssl rand -hex 32. Quan trọng: mở bất kỳ cổng nào trên một máy kết nối internet đều là rủi ro bảo mật. Đừng làm điều đó trừ khi bạn hiểu rõ hoàn toàn các tác động.

Chạy Dashboard

Muốn có một dashboard web để giám sát gateway của bạn? Đặt HERMES_DASHBOARD=1 và mở cổng 9119:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Dashboard cũng được giám sát bởi s6, vì vậy nó tự động khởi động lại nếu bị sập. Đầu ra của nó được ghi vào docker logs <container>.

Lưu ý về các rào cản vòng lặp công cụ

Đối với các gateway không có người giám sát, hãy cân nhắc bật dừng cứng cho các rào cản vòng lặp công cụ. Mặc định là false, điều này ổn cho các phiên tương tác nơi con người có thể thấy cảnh báo. Nhưng trong một gateway không có người giám sát, một agent bị kẹt trong vòng lặp có thể không bao giờ dừng lại. Thêm phần này vào config.yaml trong hồ sơ của bạn:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Tổng kết

Đó là toàn bộ câu chuyện triển khai Docker! Giờ bạn đã có một container không lưu trạng thái, có thể nâng cấp với tất cả dữ liệu được gắn an toàn trên máy chủ. Trong bài hướng dẫn tiếp theo, chúng ta sẽ khám phá dashboard chi tiết hơn. Cho đến lúc đó, chúc bạn container hóa vui vẻ!