Vận hành Cosigner

Tài liệu tham khảo CLI, sao lưu, cập nhật và giám sát.

Các lệnh

Flag toàn cục: --home (thư mục instance, mặc định là COSIGNER_HOME, sau đó là thư mục hiện tại) và --docker.

Lệnh Chức năng Flags
up Xác minh, ghép nối và khởi động một instance mới. Tương tự start sau khi đã ghép nối. --apex-endpoint --config --profile --image --token-file
start Khởi động. Yêu cầu mật khẩu ở profile manual.
stop Dừng, giữ nguyên trạng thái. Chờ các phiên kết thúc tối đa 25 giây.
restart Tạo lại container.
status ready, state, participant_id, active_sessions.
logs Log của container. --tail -f
doctor Kiểm tra máy chủ, cấu hình và chữ ký image.
info Khóa công khai, image, fingerprint của callback.
callback add Yêu cầu phê duyệt qua callback. --url --server-public-key --ca --no-restart
callback remove Ngừng yêu cầu phê duyệt. -y --no-restart
backup Sao lưu instance được mã hóa. Cosigner phải được dừng trước. --out
restore Khôi phục vào một thư mục trống. --in
export Ghi các tệp khôi phục .mshare. Chỉ profile manual, khi đã dừng. --wallet --out-dir --list
update Xác minh và cài đặt bản phát hành mới hơn sau khi sao lưu. --version --backup-out --dry-run
version Phiên bản CLI.

Biến môi trường

Biến Công dụng
COSIGNER_HOME Thư mục instance
COSIGNER_PASSWORD_FD Đọc mật khẩu lưu trữ từ một file descriptor
COSIGNER_RECOVERY_PASSWORD_FD Đọc mật khẩu sao lưu từ một file descriptor
COSIGNER_NO_UPDATE_CHECK=1 Ẩn thông báo cập nhật

Profiles

manual unattended
Khóa lưu trữ Mật khẩu (Argon2id) AWS KMS
Khởi động Nhập mật khẩu mỗi lần Tự động, khi khởi động máy
Docker tự khởi động lại no on-failure:5
Xuất .mshare Có Không

Được thiết lập khi chạy up. Không thể thay đổi sau đó.

Tự động khởi động lại

Ở profile manual, start và restart yêu cầu passphrase lưu trữ. Để chạy chúng từ script, hãy truyền passphrase qua một file descriptor với COSIGNER_PASSWORD_FD.

Từ một tệp:

chmod 600 /etc/cosigner/passphrase
COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart 3< /etc/cosigner/passphrase

Từ một secret store, để passphrase không bị ghi xuống ổ đĩa:

COSIGNER_PASSWORD_FD=3 cosigner-cli --home /srv/cosigner restart \
  3< <(gcloud secrets versions access latest --secret=cosigner-passphrase)
  • 3 là số hiệu file descriptor. Giá trị này phải từ 3 trở lên và giống nhau ở cả hai chỗ.
  • Tệp chỉ được chứa passphrase. Một ký tự xuống dòng ở cuối sẽ bị loại bỏ, mọi ký tự thừa khác sẽ khiến việc mở khóa thất bại.
  • Passphrase sai sẽ thất bại ngay lập tức, không thử lại.

Cách này kém an toàn hơn so với nhập passphrase thủ công. Bất kỳ ai có thể đọc tệp passphrase hoặc secret, và chạy được cosigner-cli, đều có thể mở khóa cosigner. Hãy giữ passphrase bên ngoài thư mục instance, không bao giờ đặt cạnh secrets/storage-kek.enc, và giới hạn những ai có thể đọc nó. Ưu tiên dùng secret store thay vì tệp.

Sao lưu và khôi phục

backup ghi một tệp lưu trữ gồm cấu hình, secret, định danh, bản ghi ghép nối, cơ sở dữ liệu đã mã hóa và nhật ký kiểm toán. Tệp được mã hóa bằng một mật khẩu khôi phục riêng (Argon2id + AES-256-GCM).

cosigner-cli stop
cosigner-cli backup --out /backups/cosigner-2026-10-12.cosrec
cosigner-cli start

Hãy ghi tệp ra ngoài thư mục instance. Dữ liệu instance được giới hạn ở 128 MiB.

cosigner-cli --home /srv/cosigner-restored restore --in /backups/cosigner-2026-10-12.cosrec
cosigner-cli --home /srv/cosigner-restored start

Hãy dừng hoặc thu hồi instance cũ trước. Không bao giờ chạy hai bản sao của cùng một cosigner.

Thường xuyên kiểm thử việc khôi phục trên một máy chủ sạch.

Xuất dữ liệu khôi phục

export ghi một tệp .mshare cho mỗi ví, được mã hóa bằng passphrase sáu từ chỉ được in ra một lần. Đây là đầu vào từ phía cosigner cho Fystack Recovery, công cụ tái tạo khóa ngoại tuyến từ số phần khóa đạt ngưỡng. Một tệp đơn lẻ không thể tái tạo khóa.

cosigner-cli stop
cosigner-cli export --out-dir /secure/recovery
cosigner-cli start

Lưu trữ passphrase tách biệt với các tệp. Xem Khôi phục khóa để có hướng dẫn đầy đủ.

Cập nhật

cosigner-cli update --dry-run
cosigner-cli update --backup-out /backups/pre-update.cosrec
  1. Chọn bản phát hành mới nhất (hoặc --version). Không hỗ trợ hạ cấp.
  2. Xác minh chữ ký và hợp đồng container.
  3. Dừng cosigner và ghi một bản sao lưu.
  4. Ghim digest mới và khởi động.

Không có cơ chế rollback tự động. Hãy giữ bản sao lưu cho đến khi phiên bản mới đã ký các giao dịch thực tế.

Giám sát

Sức khỏe: được kiểm tra mỗi 10 giây, coi là cũ sau 15 giây. Cảnh báo khi:

  • ready: false sau giai đoạn thiết lập lần khởi động đầu tiên.
  • state: callback_unavailable.
  • Container thoát (profile manual không bao giờ tự khởi động lại).

Nhật ký kiểm toán: state/audit.jsonl, được ký và liên kết chuỗi băm. Các sự kiện: session_start, session_end, session_abort, callback_decision, kek_use, identity_sign, backup_created, restore_performed. Hãy chuyển nó ra ngoài máy chủ, Docker không tự xoay vòng tệp này.

Log: Docker json-file, 10 MB x 5.

Ngừng vận hành

  1. Yêu cầu Fystack thu hồi cosigner.
  2. cosigner-cli stop.
  3. Giữ bản sao lưu cuối cùng và các tệp xuất theo chính sách lưu giữ của bạn, sau đó xóa thư mục instance.