Cài đặt Cosigner

Chế độ thông thường trên Linux với Docker. Hỗ trợ Nitro Enclave sắp ra mắt.

Yêu cầu

• Host: Linux amd64 hoặc arm64 cho production. macOS hoặc WSL 2 cho môi trường phát triển.
• Docker: Engine 20.10+ với Compose v2.
• cosign: v3+. Trình cài đặt sẽ tự thêm nếu chưa có.
• Từ Fystack: một pairing token (cps_...). Xem Bước 1.
• Máy chủ callback: bắt buộc cho production. Xem Callback phê duyệt.

Mạng: không cần cổng inbound. Cần kết nối HTTPS ra ngoài đến Apex, Fystack Gateway, ghcr.io, callback của bạn và (với profile unattended) AWS KMS.

Bước 1: Lấy pairing token

Trong dashboard Fystack, mở tab Cosigner, nhấn Register Cosigner, chọn Server rồi nhấn Continue.

Nhập tên cho cosigner. Hộp thoại hiển thị các lệnh cài đặt và một pairing token (cps_...). Hãy sao chép token: token chỉ dùng được một lần, hết hạn sau 60 phút và chỉ hiển thị một lần.

Giữ hộp thoại mở trong khi bạn hoàn thành các bước bên dưới. Hộp thoại hiển thị Waiting for your cosigner to connect và sẽ cập nhật khi cosigner ghép nối thành công.

Bước 2: Cài đặt cosigner-cli

curl -sSL https://cosigner.fystack.io/install.sh | sh

Trình cài đặt kiểm tra SHA-256 và chữ ký Sigstore của binary, sau đó cài vào /usr/local/bin (hoặc ~/.local/bin).

Bước 3: Tạo thư mục instance

Tạo một thư mục mới, trống cho cosigner này ở bất kỳ vị trí nào phù hợp trên host, và chạy các lệnh còn lại từ bên trong thư mục đó. cosigner-cli lưu toàn bộ cấu hình, secret và trạng thái của instance tại đây.

Bước 4: Kiểm tra host

cosigner-cli doctor

Kiểm tra Docker, cosign và cấu hình. Báo cáo trạng thái unconfigured, configured but unpaired hoặc paired.

Bước 5: Ghép nối và khởi động

cosigner-cli up

Sau đó up sẽ:

1. Hỏi endpoint của Fystack. Nhấn Enter để giữ giá trị mặc định.
2. Xác minh bản phát hành ghcr.io/fystack/cosigner mới nhất bằng cosign và ghim digest của nó, trước khi hỏi bất kỳ secret nào.
3. Ghi một config.yaml mặc định (profile manual, tắt callback).
4. Yêu cầu nhập mật khẩu lưu trữ và pairing token từ Bước 1.
5. Ghép nối: tạo định danh Ed25519, đăng ký với Apex và lưu state/pairing.yaml.
6. Khởi động container, mở khóa và kết nối đến Gateway.

Cấu hình mặc định dùng profile manual: khóa lưu trữ được bọc bằng mật khẩu của bạn, mật khẩu này cần nhập mỗi lần khởi động, và không tự khởi động lại. Để khởi động cùng hệ thống bằng AWS KMS, xem Profile unattended.

Bước 6: Bật phê duyệt qua callback

Cấu hình được tạo có require_callback: false, nghĩa là mọi yêu cầu Fystack gửi đến đều được ký. Hãy bật phê duyệt trước khi tạo ví:

cosigner-cli callback add https://YOUR-CALLBACK-HOST \
  --server-public-key server-public.pem

Lệnh này chỉnh sửa trực tiếp config.yaml, tạo khóa callback của cosigner trong secrets/, ghi cosigner-public.pem và khởi động lại cosigner. Sao chép cosigner-public.pem sang máy chủ callback của bạn. Xem Callback phê duyệt.

Cấu hình lúc này sẽ như sau:

storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: password_envelope
      config:
        path: /run/secrets/storage-kek.enc
approval:
  require_callback: true
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl
callback:
  timeout: 30s
  retry_count: 1
  url: https://YOUR-CALLBACK-HOST/cosigner/approve
  private_key:
    type: file
    config:
      path: /run/secrets/cosigner-private.der.hex
  response_public_key_path: /run/secrets/server-public.pem

Để điều chỉnh các thiết lập khác, như timeout hoặc retry_count, hãy sửa tệp và chạy cosigner-cli restart.

• Bên trong container, /var/lib/cosigner là thư mục state/ của instance và /run/secrets là thư mục secrets/ của instance (chỉ đọc).
• Giữ nguyên storage và audit như khi được tạo: cosigner-cli yêu cầu SQLite tại data/cosigner.db và ghi nhật ký kiểm toán vào tệp.

Bước 7: Xác minh

cosigner-cli status
cosigner-cli info
cosigner-cli logs -f

Khi status hiển thị ready, cosigner đã trực tuyến và có thể tham gia tạo khóa.

Profile unattended

Cấu hình mặc định chỉ hỗ trợ profile manual. Với unattended, khóa lưu trữ được bọc bằng khóa AWS KMS của bạn và cosigner tự khởi động cùng hệ thống. Hãy tự viết cấu hình trước Bước 5, và đặt nó bên ngoài thư mục instance (up sẽ sao chép vào):

storage:
  backend: sqlite
  sqlite:
    path: data/cosigner.db
  encryption:
    kek:
      type: kms
      config:
        provider: aws
        region: YOUR-AWS-REGION
        key_id: YOUR-KMS-KEY-ARN
        ciphertext_blob_path: /run/secrets/storage-kek.kms
approval:
  require_callback: false
audit:
  type: file
  config:
    path: /var/lib/cosigner/audit.jsonl

Mã hóa một khóa ngẫu nhiên 32 byte bằng khóa KMS của bạn và lưu bản mã base64 thành secrets/storage-kek.kms trong thư mục instance. Container cần quyền kms:Decrypt thông qua một IAM role. Sau đó chạy:

cosigner-cli up \
  --profile unattended \
  --config /secure/config.yaml

Tiếp tục với Bước 6 để bật phê duyệt qua callback.

Cấu trúc instance

Khởi động cùng hệ thống

Chỉ áp dụng cho profile unattended. Điều chỉnh systemd unit đi kèm:

[Unit]
Description=Fystack Cosigner (KMS unattended profile)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=cosigner
Group=cosigner
SupplementaryGroups=docker
ExecStart=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner start
ExecStop=/usr/local/bin/cosigner-cli --home /var/lib/fystack-cosigner stop
TimeoutStartSec=360
TimeoutStopSec=60
UMask=0077

[Install]
WantedBy=multi-user.target

Với profile manual, truyền mật khẩu qua một file descriptor:

COSIGNER_PASSWORD_FD=3 cosigner-cli start 3< /run/secrets/cosigner-pw

Cách này kém an toàn hơn so với tự nhập mật khẩu bằng tay. Xem Tự động khởi động lại.

Xử lý sự cố