---
title: "Cài đặt Cosigner"
description: "Cài đặt cosigner-cli, xác minh runtime đã ký, ghép nối với Fystack và khởi động cosigner."
url: https://docs.fystack.io/vi/cosigner/installation
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# Cài đặt Cosigner

Chế độ thông thường trên Linux với Docker. Hỗ trợ [Nitro Enclave](https://docs.fystack.io/cosigner/nitro-enclave.md) sắp ra mắt.

_Diagram: Cài đặt, xác minh, ghép nối, kết nối_

## 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](#step-1-get-a-pairing-token).
- **Máy chủ callback**: bắt buộc cho production. Xem [Callback phê duyệt](https://docs.fystack.io/cosigner/approval-callback.md).

**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**.

_Diagram: Hộp thoại Register Cosigner với tùy chọn Server được chọn_

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.

_Diagram: Hộp thoại Register Cosigner hiển thị các lệnh cài đặt, pairing token và trạng thái đang chờ kết nối_

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

```bash
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`).

| Tùy chọn | Biến môi trường | Tác dụng |
| --- | --- | --- |
| `--version vX.Y.Z` | `COSIGNER_VERSION` | Cài đặt một phiên bản cụ thể |
| `--dir DIR` | `COSIGNER_INSTALL_DIR` | Vị trí cài đặt |
| `--skip-docker-check` |  | Bỏ qua kiểm tra Docker |

> **Note:** Để xác minh trình cài đặt trước khi chạy, xem [Xác minh chuỗi cung ứng](https://docs.fystack.io/cosigner/security.md#supply-chain-verification).

## 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

```bash
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

```bash
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.

_Diagram: Kết quả của cosigner-cli up: image đã được xác minh và ghim, lưu trữ đã mở khóa, đã ghép nối với Apex, cosigner đang chạy_

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](#unattended-profile).

## 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í:

```bash
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](https://docs.fystack.io/cosigner/approval-callback.md).

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

```yaml
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

```bash
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):

```yaml
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:

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

Tiếp tục với [Bước 6](#step-6-turn-on-callback-approval) để bật phê duyệt qua callback.

## Cấu trúc instance

| Đường dẫn | Nội dung |
| --- | --- |
| `cosigner-cli.yaml` | Endpoint Apex, digest image đã ghim, profile |
| `config.yaml` | Cấu hình runtime (chỉ đọc) |
| `docker-compose.yaml` | Tệp Compose được tạo tự động và đã gia cố |
| `secrets/` | Khóa lưu trữ đã bọc và các khóa callback |
| `state/pairing.yaml` | Bản ghi ghép nối từ Apex |
| `state/cosigner.key` | Khóa định danh Ed25519 |
| `state/data/cosigner.db` | Các phần khóa đã mã hóa và trạng thái phiên |
| `state/audit.jsonl` | Nhật ký kiểm toán có chữ ký |

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

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

```ini
[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:

```bash
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](https://docs.fystack.io/cosigner/operations.md#automate-restart).

## Xử lý sự cố

| Triệu chứng | Cách khắc phục |
| --- | --- |
| Image signature verification failed | Không được bỏ qua. Kiểm tra tham chiếu image và liên hệ security@fystack.io. |
| identity already registered | Khôi phục dữ liệu ghép nối ban đầu từ bản sao lưu thay vì ghép nối lại. |
| Thoát ngay sau khi khởi động | Ping callback khi khởi động thất bại. Kiểm tra callback có thể truy cập được và tin cậy `cosigner-public.pem`. |
| AlreadyExists | Một instance khác với cùng định danh đang kết nối. Hãy dừng instance đó. |
| PermissionDenied | Cosigner đã bị thu hồi. Cosigner sẽ không kết nối lại. |
| Chưa sẵn sàng sau lần khởi động đầu tiên | Đang tạo tham số chuẩn bị trước ECDSA. Chờ tối đa 5 phút. |