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.
Vuốt ngang để xem hết sơ đồ.
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ần | Dùng cho | Ghi chú |
|---|---|---|
| Kubernetes 1.27 trở lên, Ingress controller, cert-manager hoặc chứng chỉ có sẵn | Tara, Ryoma | Claude 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 database | Tara, Ryoma | Tara 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 versioning | Tara | Khóa truy cập chỉ có quyền trên đúng bucket đó |
| Vault hoặc OpenBao với Transit và khóa Ed25519 | Tara | Giữ khóa ký gói, thay cho file khóa |
| ClickHouse 26.x | Ryoma | Cổng native. Cần một user ghi cho Collector và hai user chỉ đọc cho Grafana |
| Registry riêng của tổ chức | Tara, Ryoma | Chứa image tara-api, tara-portal, ryoma-api |
| Mạng nội bộ hoặc VPN | Grafana | Không mở Grafana ra Internet |
| ClamAV | Tara | Tù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.
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 RyomaGiá 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.secretName | Host duy nhất của Tara. TARA_PUBLIC_URL và TARA_PORTAL_URL suy ra từ đây |
s3.endpoint, s3.bucket, s3.region, s3.pathStyle | Kho gói. Khóa truy cập nằm trong Secret |
signing.vault.addr, .mount, .key | Khóa ký trong Transit. Token Vault nằm trong Secret TARA_SIGNING_VAULT_TOKEN |
worker.mode | embedded 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.enabled | Bậ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.existingSecret | Tên Secret có sẵn chứa các khóa bí mật |
migration.seedConfig | true (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.existingSecret | Secret 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.env | production (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.githubOrg | Chỉ 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.scmPlugin | Kit scm GitHub cho Ryoma (RYOMA_SCM_PLUGIN), dạng name@version:sha256. Sha256 lấy ở trang tài nguyên trên Tara |
config.scmGitlabPlugin | Kit 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.scmServerTokenOrgs | Khô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.taraKeys | Tara cấp danh tính cho Ryoma, kèm khóa công khai của Tara |
collector.clickhouseEndpoint, collector.rawTTL | ClickHouse 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.enabled | Mặc định tắt. Chỉ bật với IngressClass nội bộ hoặc VPN |
api.replicas | Số 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.
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.
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 trongRyoma/deploy/clickhouse/, hoặc lệnh SQL tương đương.Cài Tara:
bashhelm upgrade --install tara Tara/deploy/helm/tara -n tara -f values-production.yaml -f rieng.yamlJob 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.
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.Phát hành Phillip và công cụ lên Tara bằng
tara-admin phillip-releasevàtara-admin tool-release. Sau đó tạo token Tara chỉ đọc cho Ryoma bằngph tara tokens create ryomavà đưa vào Secret của Ryoma.Cài Ryoma bằng
helm upgrade --install ryoma Ryoma/deploy/helm/ryoma -n ryoma -f ....ryoma-apitự migrate PostgreSQL và ClickHouse. Bảngotel_logsdo Collector tạo, nên podryoma-apicó startupProbe rộng để chờ Collector lên trước.Tạo user chỉ đọc cho Grafana trên PostgreSQL bằng file
Ryoma/deploy/postgres/grafana-user.sql.Đăng ký client
grafanatrongTARA_OAUTH_CLIENTScủa Tara, rồi nâng cấp Tara. Jobgrafana-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 targetdocs-web) với Ingress riêng ởdocs.host(mặc địnhphillipcli.cloud). Tổ chức tự dựng build bằngDOCS_TARA_URL(địa chỉ Tara hiển thị trong bài),DOCS_URLvàDOCS_DEVELOP_URL(trang developer mà nó link tới), rồi trỏ Portal tới trang này bằng build argDOCS_URL. Trang trạng thái gọi Tara từ trình duyệt, nên/healthzvà/phillip/latest.jsoncủ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 targetdevelop-web, hostdevelop.host, mặc địnhdevelopers.phillipcli.cloud). Build bằngDOCS_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: đặtdevelop.internal.enabled=true(cầnadmin.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ệu | Cách sao lưu |
|---|---|
| PostgreSQL của Tara | pg_dump hoặc snapshot kèm WAL. Đây là nguồn sự thật của version, vai trò và audit |
| Bucket S3 | Bậ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 Ryoma | Sao lưu như Tara |
| ClickHouse | clickhouse-backup hoặc snapshot volume. Dữ liệu thô tự hết hạn theo collector.rawTTL |
| Grafana | Snapshot 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ó.
- Chạy
helm lintvàhelm templatecho cả hai chart. - 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. - 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.
- Từ một máy người dùng thật, chạy
ph setuprồiph 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. - Trỏ
PHILLIP_RYOMA_URLvào Ryoma rồi chạyph forge doctor. Logryoma-apiphải có người dùng và tổ chức, và dashboard Grafana ra số liệu. - Đă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.