Bỏ qua, đến phần nội dung

Triển khai bằng Helm ​

Tara và Ryoma chạy trên Kubernetes, mỗi dịch vụ có một chart Helm trong repo của mình. Trang này đi qua hạ tầng cần chuẩn bị, những giá trị Helm bạn thường phải đặt, thứ tự cài và cách kiểm tra sau khi cài. Bandum không nằm ở đây vì nó chạy local trên máy người dùng, và Tara hay Ryoma không bao giờ gọi vào Bandum.

Sơ đồ triển khai online. Ingress nhận hai host. Host của Tara chuyển vào Portal, Tara API và worker. Tara API dùng PostgreSQL, kho S3 hoặc MinIO và Vault hoặc OpenBao. Host của Ryoma chuyển vào Ryoma API. Ryoma API chuyển telemetry cho Collector, Collector ghi vào ClickHouse, Grafana đọc từ ClickHouse. Trang developer là một site tĩnh riêng, có host riêng.IngressPortal và Tara API chung một host; trang developer có host riêngTaraPortalwebTara APIkho và duyệtWorkertác vụ nềnPostgreSQLnguồn sự thậtS3 / MinIOkho góiVault / OpenBaokhóa ký góiRyomaRyoma APInhận, xác thựcCollectorlọc dữ liệuGrafanadashboardClickHousesố liệu thôvà số đếmtara.phillipcli.cloudryoma.phillipcli.cloud

Vuốt ngang để xem hết sơ đồ.

Hạ tầng nền như PostgreSQL, S3, Vault và ClickHouse bạn dựng trước, chart Helm chỉ tham chiếu tới chúng.

Hạ tầng cần có ​

Chart chỉ tham chiếu các thành phần dưới đây chứ không cài kèm, nên bạn dựng chúng trước.

Thành phầnDùng choGhi chú
Kubernetes 1.27 trở lên, Ingress controller, cert-manager hoặc chứng chỉ có sẵnTara, RyomaClaude Code chỉ tải gói qua HTTPS, nên Tara cần chứng chỉ mà máy người dùng tin
PostgreSQL 17, mỗi dịch vụ một databaseTara, RyomaTara coi đây là nguồn sự thật về version, vai trò và audit
S3 hoặc MinIO, bucket tạo sẵn và bật versioningTaraKhóa truy cập chỉ có quyền trên đúng bucket đó
Vault hoặc OpenBao với Transit và khóa Ed25519TaraGiữ khóa ký gói, thay cho file khóa
ClickHouse 26.xRyomaCổng native. Cần một user ghi cho Collector và hai user chỉ đọc cho Grafana
Registry riêng của tổ chứcTara, RyomaChứa image tara-api, tara-portal, ryoma-api
Mạng nội bộ hoặc VPNGrafanaKhông mở Grafana ra Internet
ClamAVTaraTùy chọn. Chart có sẵn, bật bằng clamav.enabled

Bạn cần ba tên miền. Tara dùng chung một host cho Portal và API, ví dụ tara.phillipcli.cloud. Ryoma có host riêng để nhận telemetry, ví dụ ryoma.phillipcli.cloud. Grafana có host nội bộ.

Build image ​

Tara build hai image từ cùng một Dockerfile, còn Ryoma build một image và cần mã dùng chung của Bandum.

bash
docker build --target api --build-arg VERSION=0.1.0 -t <registry>/tara/tara-api:0.1.0 Tara
docker build --target portal -t <registry>/tara/tara-portal:0.1.0 Tara
docker build --build-context bandum-pkg=Bandum/pkg -t <registry>/ryoma/ryoma-api:0.1.0 Ryoma

Giá trị Helm thường đặt ​

Mỗi chart có values.yaml đầy đủ kèm chú thích, cùng values-staging.yaml và values-production.yaml. Bạn ghi đè bằng một file riêng cho môi trường của mình. File này không được chứa bí mật, vì bí mật nằm trong một Secret có sẵn mà chart tham chiếu qua secrets.existingSecret.

Giá trị chính của Tara là:

Giá trịÝ nghĩa
image.api.*, image.portal.*Image và tag
ingress.host, ingress.tls.secretNameHost duy nhất của Tara. TARA_PUBLIC_URL và TARA_PORTAL_URL suy ra từ đây
s3.endpoint, s3.bucket, s3.region, s3.pathStyleKho gói. Khóa truy cập nằm trong Secret
signing.vault.addr, .mount, .keyKhóa ký trong Transit. Token Vault nằm trong Secret TARA_SIGNING_VAULT_TOKEN
worker.modeembedded chạy worker chung tiến trình API, hợp cho staging. separate tách worker ra Deployment riêng, nên dùng cho production
clamav.enabledBật quét mã độc
config.*Phần còn lại của biến TARA_* không bí mật, như ryomaUrl, grafanaUrl, apps
secrets.existingSecretTên Secret có sẵn chứa các khóa bí mật
migration.seedConfigtrue (mặc định): Job migration chạy thêm tara-admin seed-config để tạo tổ chức và nạp catalog model. Chạy lại nhiều lần vẫn an toàn
migration.existingSecretSecret thứ hai chỉ Job migration đọc: TARA_MIGRATE_DATABASE_URL (chủ cơ sở dữ liệu) và TARA_APP_DB_PASSWORD (mật khẩu role tara_app). Bắt buộc khi dùng secrets.existingSecret
config.envproduction (mặc định): API và worker không khởi động nếu role cơ sở dữ liệu là superuser hoặc có BYPASSRLS
config.singleOrg, config.githubOrgChỉ cho bản tự cài một tổ chức: slug của tổ chức, và (tùy chọn) tổ chức GitHub có thành viên tự vào lúc đăng nhập. Để trống là chế độ nhiều tổ chức (SaaS): ai cũng đăng nhập được, tự tạo hoặc tham gia tổ chức. Xem Tự cài một tổ chức

Role cơ sở dữ liệu. Tara cách ly các tổ chức bằng Row-Level Security của PostgreSQL, mà superuser thì bỏ qua RLS. Vì vậy TARA_DATABASE_URL trong Secret của Tara phải kết nối bằng role tara_app (không superuser, không BYPASSRLS). Job migration kết nối bằng chủ cơ sở dữ liệu qua migration.existingSecret, mỗi lần chạy tạo hoặc cập nhật role đó và cấp quyền trên mọi bảng, gồm quyền mặc định cho bảng tạo sau. API và worker không bao giờ thấy thông tin của chủ cơ sở dữ liệu.

Secret của Tara cần ít nhất TARA_DATABASE_URL, TARA_S3_ACCESS_KEY, TARA_S3_SECRET_KEY và TARA_SIGNING_VAULT_TOKEN. Tùy cách đăng nhập, bạn thêm TARA_GITLAB_PROVIDERS hoặc TARA_GITHUB_CLIENT_SECRET, và TARA_OAUTH_CLIENTS cho web app như Grafana. TARA_DELEGATION_KEY (bí mật ngẫu nhiên từ 32 ký tự, openssl rand -hex 32) cho Portal đọc dữ liệu dự án từ Ryoma thay cho người đang đăng nhập: Tara ký một token ngắn hạn, chỉ đọc, gắn đúng người dùng và tổ chức đó. Chỉ tara-api giữ khóa này; đừng dùng lại làm credential của Ryoma hay Bandum. Cách đăng ký OAuth app và lấy các giá trị này ở Chuẩn bị GitHub và GitLab.

Giá trị chính của Ryoma là:

Giá trịÝ nghĩa
api.ingress.hostĐịa chỉ Phillip gửi telemetry tới, tức PHILLIP_RYOMA_URL
config.scmPluginKit scm GitHub cho Ryoma (RYOMA_SCM_PLUGIN), dạng name@version:sha256. Sha256 lấy ở trang tài nguyên trên Tara
config.scmGitlabPluginKit scm GitLab (RYOMA_SCM_GITLAB_PLUGIN), dạng kit-scm-gitlab@<version>:<sha256>. Mặc định trống, nghĩa là repo GitLab không được đọc. Cần có config.scmPlugin và khóa RYOMA_TARA_SCM_TOKEN trong Secret của Ryoma, và dự án phải khai repo dạng URL (https://host/nhóm/tên)
config.scmServerTokenOrgsKhông dùng nữa. Slug các tổ chức được dùng token SCM chỉ đọc riêng của máy chủ để lấy task và PR. Mặc định trống. Chỉ còn là đường lùi cho bản cài một tổ chức hoặc GitLab, và tổ chức có GitHub App không bao giờ dùng. Xem Tham chiếu tự cài
config.taraUrl, config.taraKeysTara cấp danh tính cho Ryoma, kèm khóa công khai của Tara
collector.clickhouseEndpoint, collector.rawTTLClickHouse và thời gian giữ log thô
clickhouse.*, postgres.*Datasource cho Grafana
grafana.rootUrl, grafana.oauth.*Địa chỉ Grafana và đăng nhập qua Tara
grafana.ingress.enabledMặc định tắt. Chỉ bật với IngressClass nội bộ hoặc VPN
api.replicasSố bản sao ryoma-api, production mặc định 2

Secret của Ryoma cần RYOMA_DATABASE_URL, RYOMA_CLICKHOUSE_URL, RYOMA_TARA_TOKEN, thông tin ClickHouse và mật khẩu của Grafana. Grafana chỉ dành cho người vận hành, xem Grafana cho người vận hành.

Chạy nhiều bản sao ryoma-api ​

Khi api.replicas lớn hơn 1, mọi bản đều nhận telemetry và webhook. Các vòng việc nền, như đánh giá hạn mức, chép task, bản tin tuần và tính sẵn số liệu cho Grafana, chỉ chạy trên một bản giữ khóa leader trong PostgreSQL. Leader chết thì khóa tự nhả và một bản khác tiếp quản sau tối đa config.leaderRetry, mặc định 15 giây.

Bạn không cần thêm hạ tầng nào ngoài PostgreSQL đang dùng. Mỗi bản sao giữ thêm một connection riêng, nên hãy tính vào max_connections. Nếu bạn đặt PgBouncer ở giữa, hãy dùng chế độ session hoặc nối thẳng cho RYOMA_DATABASE_URL, vì khóa mức session không sống qua transaction pooling. Muốn tách hẳn worker thì chạy thêm một Deployment từ cùng chart và image với RYOMA_BACKGROUND=off cho các bản HTTP.

Thứ tự cài ​

Thứ tự này quan trọng vì Ryoma cần Tara đã phát hành công cụ và cấp token.

  1. Chuẩn bị hạ tầng ngoài: hai database PostgreSQL, bucket S3, khóa Transit, ClickHouse, DNS, chứng chỉ và Secret cho hai chart.

  2. Trên ClickHouse, tạo database otel, user ghi cho Collector và hai user chỉ đọc cho Grafana bằng các file mẫu trong Ryoma/deploy/clickhouse/, hoặc lệnh SQL tương đương.

  3. Cài Tara:

    bash
    helm upgrade --install tara Tara/deploy/helm/tara -n tara -f values-production.yaml -f rieng.yaml

    Job migration chạy trước khi API đổi phiên bản. Nếu migration lỗi thì bản cũ vẫn chạy.

  4. Cho một tài khoản đã đăng nhập làm owner đầu tiên (tara-admin grant <login> <org> owner) và, với đội của bạn, tạo tài khoản staff của admin console (tara-admin staff create <login> --role moderator --email <email>; tài khoản khách không có cờ nền tảng nào). Sau đó lấy khóa công khai của Tara từ GET /v1/signing-keys để đặt vào cấu hình của Ryoma và Phillip.

  5. Phát hành Phillip và công cụ lên Tara bằng tara-admin phillip-release và tara-admin tool-release. Sau đó tạo token Tara chỉ đọc cho Ryoma bằng ph tara tokens create ryoma và đưa vào Secret của Ryoma.

  6. Cài Ryoma bằng helm upgrade --install ryoma Ryoma/deploy/helm/ryoma -n ryoma -f .... ryoma-api tự migrate PostgreSQL và ClickHouse. Bảng otel_logs do Collector tạo, nên pod ryoma-api có startupProbe rộng để chờ Collector lên trước.

  7. Tạo user chỉ đọc cho Grafana trên PostgreSQL bằng file Ryoma/deploy/postgres/grafana-user.sql.

  8. Đăng ký client grafana trong TARA_OAUTH_CLIENTS của Tara, rồi nâng cấp Tara. Job grafana-init đã dựng org và dashboard khi cài Ryoma.

Nếu bạn đã có gói ở thư mục local từ trước, lệnh tara-admin artifacts-copy <thư mục> --dry-run cho xem trước việc chép lên S3. Bỏ --dry-run để chép thật và kiểm sha256.

Ingress và các trang tài liệu ​

Ingress của Tara dùng một host cho cả Portal và API. Các đường dẫn do API xử lý như /v1, /auth, /oauth, /claude, /phillip, /tools, /install.sh và /healthz đi tới API, còn lại đi tới Portal. Nhờ cùng origin nên cookie phiên chạy được mà không cần CORS. Ingress cần cho phép body lớn đến 220 MB vì gói tối đa 200 MiB.

PhillipCLI xuất bản hai site tĩnh, build từ một dự án VitePress. Cả hai đều không thuộc Portal và không lộ API hay Portal, nên ra Internet được dù Tara nằm sau VPN.

  • Trang tài liệu dành cho khách hàng. Chart triển khai nó thành một thành phần riêng (docs.enabled, image target docs-web) với Ingress riêng ở docs.host (mặc định phillipcli.cloud). Tổ chức tự dựng build bằng DOCS_TARA_URL (địa chỉ Tara hiển thị trong bài), DOCS_URL và DOCS_DEVELOP_URL (trang developer mà nó link tới), rồi trỏ Portal tới trang này bằng build arg DOCS_URL. Trang trạng thái gọi Tara từ trình duyệt, nên /healthz và /phillip/latest.json của Tara phải cho phép origin của trang tài liệu qua CORS.
  • Trang developer là trang bạn đang đọc (develop.enabled, image target develop-web, host develop.host, mặc định developers.phillipcli.cloud). Build bằng DOCS_PUBLIC_URL (trang tài liệu mà nó link ngược về). Mục Internal chỉ dành cho staff của admin console: đặt develop.internal.enabled=true (cần admin.enabled=true: người đọc đăng nhập ở admin console bằng tài khoản staff) và để TARA_DOCS_INTERNAL_KEY (từ 32 ký tự ngẫu nhiên) trong Secret. Thiếu hai thứ này thì mục Internal đóng với mọi người. Nginx của trang gọi API ngay trong cụm (develop.taraInternalUrl, mặc định là Service API của release) để kiểm vé đăng nhập.

Link cũ tara.<host>/docs chỉ được chuyển hướng ở single-host (Caddy), chart này không làm việc đó.

Sao lưu ​

Bạn nên có kế hoạch sao lưu cho từng loại dữ liệu và thử khôi phục định kỳ vào môi trường staging.

Dữ liệuCách sao lưu
PostgreSQL của Tarapg_dump hoặc snapshot kèm WAL. Đây là nguồn sự thật của version, vai trò và audit
Bucket S3Bật versioning, và object lock hoặc replication nếu có. Gói không sửa được nên bucket gần như chỉ thêm
Khóa kýNằm trong Transit, sao lưu theo quy trình của Vault hoặc OpenBao. Mất khóa thì mọi gói phải ký lại bằng tara-admin sign-published --resign
PostgreSQL của RyomaSao lưu như Tara
ClickHouseclickhouse-backup hoặc snapshot volume. Dữ liệu thô tự hết hạn theo collector.rawTTL
GrafanaSnapshot PVC hoặc dùng database ngoài. Dashboard dựng lại được từ chart

Kiểm tra sau khi cài ​

Bạn kiểm theo thứ tự từ dễ đến khó.

  1. Chạy helm lint và helm template cho cả hai chart.
  2. Gọi https://tara.phillipcli.cloud/healthz, lệnh này kiểm cả PostgreSQL. Gọi thêm /install.sh để chắc script cài ra đúng.
  3. Phát hành một tài nguyên mẫu, rồi kiểm gói nằm trong bucket và sha256 khớp.
  4. Từ một máy người dùng thật, chạy ph setup rồi ph tara install <tài nguyên>. Claude Code phải tự tải gói qua HTTPS, kèm header xác thực, và kiểm sha256.
  5. Trỏ PHILLIP_RYOMA_URL vào Ryoma rồi chạy ph forge doctor. Log ryoma-api phải có người dùng và tổ chức, và dashboard Grafana ra số liệu.
  6. Đăng nhập Grafana qua Tara từ mạng nội bộ, bằng tài khoản admin riêng của Grafana (Tara không còn cấp quyền Admin Grafana cho tài khoản khách). Ngoài VPN thì không vào được, và khách hàng không dùng Grafana.

Nâng cấp ​

Bạn nâng cấp bằng đúng lệnh helm upgrade --install với tag image mới. Bên Tara, job migration chạy trước khi API đổi phiên bản, nên migration lỗi thì release dừng và bản đang chạy không bị ảnh hưởng. Bên Ryoma, ryoma-api tự migrate khi khởi động. Trước mỗi lần nâng cấp lớn, hãy chắc là bản sao lưu PostgreSQL mới nhất dùng được.

Đọc thêm ​