Chuyển tới nội dung chính

Trình quản lý bí mật Bitwarden

Kéo khóa API từ Bitwarden Secrets Manager khi khởi động quá trình thay vì lưu trữ chúng ở dạng bản rõ bên trong

~/.Hermes/.env

. Một bí mật khởi động (mã thông báo truy cập tài khoản máy) thay thế N khóa cho mỗi nhà cung cấp và việc xoay vòng thông tin xác thực sẽ trở thành một thay đổi duy nhất trong ứng dụng web Bitwarden.

Cách thức hoạt động​

  1. Bạn tạo tài khoản máy trong Trình quản lý bí mật Bitwarden, cấp cho nó quyền truy cập đọc vào dự án và tạo mã thông báo truy cập.
  2. Hermes lưu trữ mã thông báo duy nhất đó trong

~/.Hermes/.env dưới dạng BWS_ACCESS_TOKEN

. 3. Mỗi khi Hermes (hoặc cổng hoặc công việc định kỳ) bắt đầu, sau khi

~/.Hermes/.env được tải, Hermes gọi bws secret list <project_id và đặt các khóa được trả về vào os.environ

. 4. Theo mặc định, Hermes ghi đè các giá trị đã có trong môi trường của bạn, vì vậy Bitwarden là nguồn gốc của sự thật — xoay khóa một lần trong ứng dụng web và mọi quy trình của Hermes sẽ chọn khóa đó vào lần bắt đầu tiếp theo. Lật override_existing: false trong cấu hình nếu bạn muốn

.env ` giành chiến thắng.

Tệp nhị phân bws được tự động tải xuống

~/.Hermes/bin/ trong lần sử dụng đầu tiên — không có apt

, không có `brew

, không có `sudo

.

Tại sao lại có tài khoản trên máy (và tại sao không có lời nhắc 2FA)​

Trình quản lý bí mật Bitwarden được thiết kế cho khối lượng công việc không tương tác: tài khoản máy không thể bị kiểm soát 2FA vì không có con người trong vòng lặp. Mã thông báo truy cập là thông tin xác thực. Bất kỳ ai có nó đều có thể đọc mọi bí mật mà tài khoản máy có quyền truy cập, vì vậy hãy coi nó như mã thông báo mang giá trị cao - lưu trữ nó trong

.env (không phải config.yaml

) và thu hồi + tạo lại từ ứng dụng web Bitwarden nếu nó bị rò rỉ.

Bạn thiết lập tài khoản máy trong ứng dụng web, nơi áp dụng 2FA thông thường của bạn. Sau đó, mã thông báo sẽ tự động.

Thiết lập​

1. Tạo tài khoản máy và access token​

Trong Bitwarden web app (hoặc vault.bitwarden.eu cho tài khoản EU):

  1. Chuyển sang Trình quản lý bí mật từ trình chuyển đổi sản phẩm.
  2. Tạo hoặc chọn Dự án (ví dụ: "Chìa khóa Hermes").
  3. Thêm khóa nhà cung cấp của bạn làm bí mật. Bí mật Tên trở thành tên biến môi trường - sử dụng `OpenRouter_API_KEY

, `Anthropic_API_KEY

, v.v. 4. Tài khoản máy → Tài khoản máy mới → Máy Hermes của tôi → tab Dự án → cấp quyền truy cập Đọc cho dự án của bạn. 5. Tab Mã thông báo truy cập → Tạo mã thông báo truy cập → Không bao giờ hết hạn (hoặc chọn ngày) → sao chép mã thông báo (bắt đầu bằng

). Bitwarden không thể lấy lại nó - hãy giữ bản sao.

Trình quản lý bí mật được bao gồm trong bậc miễn phí của Bitwarden với các giới hạn; không cần gói trả phí để thử điều này.

2. Chạy trình hướng dẫn​

Hermes secrets bitwarden setup

`
``Nó sẽ:
1. Tải xuống và xác minh 
`bws v2.0.0
` vào 

~/.Hermes/bin/bws

.

2. Nhắc bạn nhập mã thông báo truy cập (đầu vào bị ẩn). Được lưu trữ trong 

~/.Hermes/.env
` dưới dạng 
`BWS_ACCESS_TOKEN

.
3. Hỏi xem tài khoản máy của bạn thuộc khu vực Bitwarden nào — **US Cloud**, **EU Cloud** hoặc **self-hosted / custom URL**. Được lưu trữ trong 
`config.yaml
` dưới dạng 
`secrets.bitwarden.server_url
` và được chuyển đến 
`bws
` dưới dạng 
`BWS_SERVER_URL

.
4. Liệt kê các dự án mà tài khoản máy có thể xem; chọn một. Được lưu trữ trong 
`config.yaml
` dưới dạng 
`secrets.bitwarden.project_id

.
5. Tìm nạp thử các bí mật của dự án và cho bạn biết các loại env nào sẽ giải quyết được.
6. Lật 
`secrets.bitwarden.enabled: true

.

Thiết lập không tương tác cũng được hỗ trợ thông qua cờ:

``` bash
Hermes secrets bitwarden setup \

  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.eu \
  --project-id &lt;project-uuid

`

### 3. Xác nhận

``` bash
Hermes secrets bitwarden status

`
``Từ giờ trở đi, mọi lệnh gọi 
`Hermes
` đều mang theo những bí mật mới khi khởi động. Bạn sẽ thấy bản tóm tắt một dòng trong stderr khi các bí mật lần đầu tiên được áp dụng trong một quy trình.`##CLI

| Lệnh | Nó làm gì |
|---|---|
| 
`Hermes secrets bitwarden setup
` | Trình hướng dẫn tương tác (cài đặt nhị phân, nhắc mã thông báo, chọn dự án, tìm nạp thử) |
| 
`Hermes secrets bitwarden status
` | Hiển thị cấu hình + phiên bản nhị phân + sự hiện diện của mã thông báo |
| 
`Hermes secrets bitwarden sync
` | Chạy thử: lấy bí mật ngay bây giờ và hiển thị những gì sẽ được áp dụng |
| 
`Hermes secrets bitwarden sync --apply
` | Kéo và xuất vào môi trường của shell hiện tại |
| 
`Hermes secrets bitwarden install
` | Chỉ cần tải xuống tệp nhị phân 
`bws
` đã ghim (không cần xác thực) |
| 
`Hermes secrets bitwarden disable
` | Lật 
`enabled: false

; để lại mã thông báo + id dự án |

## Cấu hình

Mặc định trong 

~/.Hermes/config.yaml

:

`YAML
secrets:
  bitwarden:
    enabled: false
    access_token_env: BWS_ACCESS_TOKEN
    project_id: ""
    server_url: ""
    cache_ttl_seconds: 300
    override_existing: true
    auto_install: true

`

| Chìa khóa | Mặc định | Nó làm gì |
|---|---|---|
| 
`enabled
` | 
`false
` | Công tắc chính. Khi sai, Bitwarden sẽ không bao giờ được liên lạc. |
| 
`access_token_env
` | 
`BWS_ACCESS_TOKEN
` | Tên Env var chứa mã thông báo bootstrap. Thay đổi điều này nếu bạn đã sử dụng 
`BWS_ACCESS_TOKEN
` cho mục đích khác. |
| 
`project_id
` | 

""
` | UUID của dự án để đồng bộ hóa. |
| 
`server_url
` | 

""
` | Vùng Bitwarden hoặc điểm cuối tự lưu trữ. Trống = 
`bws
` mặc định (US Cloud, 
`https://vault.bitwarden.com

). Đặt thành 
`https://vault.bitwarden.eu
` cho Đám mây EU hoặc URL của riêng bạn để tự lưu trữ. Đưa vào quy trình con 
`bws
` dưới dạng 
`BWS_SERVER_URL

. |
| 
`cache_ttl_seconds
` | 
`300
` | Thời gian sử dụng lại kết quả tìm nạp trong quá trình. Đặt thành 
`0
` để tắt bộ nhớ đệm. Bộ nhớ đệm dành cho mỗi quá trình; các lệnh gọi 
`Hermes
` mới bắt đầu mới. |
| 
`override_existing
` | 
`true
` | Khi đúng, các giá trị Bitwarden sẽ ghi đè lên mọi thứ đã có trong env (vì vậy việc xoay trong ứng dụng web thực sự có hiệu lực). Chuyển sang 
`false
` nếu bạn muốn 

.env
` / xuất khẩu vỏ giành chiến thắng tại địa phương. |
| 
`auto_install
` | 
`true
` | Khi đúng, 
`bws
` sẽ tự động được tải xuống 

~/.Hermes/bin/
` trong lần sử dụng đầu tiên. |

## Chế độ lỗi

Bitwarden không bao giờ chặn khởi động Hermes. Nếu có sự cố xảy ra, bạn sẽ thấy cảnh báo một dòng trong stderr và Hermes tiếp tục với bất kỳ thông tin xác thực nào 

.env
` đã có:

| Triệu chứng | Nguyên nhân | Sửa chữa |
|---|---|---|
| 
`BWS_ACCESS_TOKEN is not set
` | Đã bật trong cấu hình nhưng mã thông báo đã bị xóa khỏi 

.env
` | Chạy lại 
`Hermes secrets bitwarden setup
` |
| 
`bws exited 1: invalid access token
` | Mã thông báo bị thu hồi hoặc sai | Tạo mã thông báo mới, chạy lại thiết lập |
| 

[400 Bad Request] \&#123;"error":"invalid_CLIent"&#125;
` | Mã thông báo dành cho khu vực Bitwarden không phải khu vực 
`bws
` đang gọi (ví dụ: mã thông báo EU chạm vào điểm cuối nhận dạng của Hoa Kỳ) | Chạy lại thiết lập và chọn vùng phù hợp hoặc đặt 
`secrets.bitwarden.server_url
` thành 
`https://vault.bitwarden.eu
` (hoặc URL tự lưu trữ của bạn) |
| 
`bws timed out
` | Mạng bị chặn hoặc API Bitwarden chậm | Kiểm tra kết nối với 
`API.bitwarden.com
` (hoặc 
`server_url
` của bạn) |
| 
`bws binary not available
` | 
`auto_install: false
` và 
`bws
` không có trên PATH | Cài đặt thủ công từ [GitHub.com/bitwarden/SDK-sm/releases](https://GitHub.com/bitwarden/SDK-sm/releases) hoặc bật lại 
`auto_install
` |
| 
`Checksum mismatch
` | Tải xuống bị hỏng hoặc giả mạo | Chạy lại, sẽ thử lại; nếu tình trạng này vẫn tiếp diễn, hãy báo cáo sự cố |

## Ghi chú bảo mật
- Mã thông báo khởi động (
`BWS_ACCESS_TOKEN

) bản thân nó rất nhạy cảm — bất kỳ ai có mã thông báo này đều có thể đọc mọi bí mật mà tài khoản máy có quyền truy cập. Hãy đối xử với nó giống như bất kỳ khóa API nào khác.

- Hermes sẽ từ chối để Bitwarden ghi đè mã thông báo bootstrap, ngay cả với 
`override_existing: true

. Nếu bạn lưu trữ 
`BWS_ACCESS_TOKEN
` dưới dạng bí mật bên trong dự án, nó sẽ âm thầm bị bỏ qua trong quá trình áp dụng.
- Tải xuống nhị phân 
`bws
` được xác minh dựa trên tổng kiểm tra SHA-256 đã xuất bản từ cùng một bản phát hành GitHub. Không khớp sẽ hủy bỏ quá trình cài đặt.
- Phiên bản được ghim (
`bws v2.0.0
` tại thời điểm viết bài) được cập nhật thông qua PR cho repo này - Hermes không tự động nâng cấp 
`bws
` lên "mới nhất" vì hình dạng phát hành ngược dòng có thể thay đổi.

## Khi nào KHÔNG nên sử dụng cái này
- **Thiết lập cá nhân trên một máy** trong đó 

~/.Hermes/.env
` là phù hợp. Bạn đang trao đổi thông tin xác thực này với thông tin xác thực khác và thêm phần phụ thuộc vào mạng khi khởi động.
- **Môi trường air-gapped** không thể đạt tới 
`API.bitwarden.com

.
- **CI/CD** trong đó cơ chế đưa bí mật hiện có (bí mật GitHub Actions, Vault, v.v.) đã được thiết lập — chọn một đường dẫn chứ không phải hai đường dẫn.

Trường hợp tốt cho việc này là nhóm nhiều máy, hộp phát triển dùng chung, VPS cổng hoặc bất kỳ thiết lập nào mà bạn muốn xoay vòng và thu hồi tập trung trên nhiều bản cài đặt Hermes.