Files

T

thanhnv 114340c719 feat: harden CASAN production install lifecycle

2026-07-24 11:11:44 +07:00

10 KiB

Raw Permalink Blame History

Dùng CASAN local để làm dự án — hướng dẫn từng bước

Tài liệu này dành cho môi trường local hiện tại: macOS chạy Control Panel và model local, Docker chạy hạ tầng, máy Linux thanhnv@192.168.1.5 là tài nguyên mở rộng khi cần. Production là một giai đoạn riêng.

1. Hiểu CASAN trong một phút

CASAN không phải là một model AI mới. CASAN là lớp điều phối và kiểm soát nằm giữa người dùng, model và công cụ.

flowchart LR
    U["Mục tiêu / câu hỏi"] --> H1["H1 Context"]
    H1 --> H2["H2 Local worker / tools"]
    H2 --> H3["H3 Cloud review / eval"]
    H3 --> H4["H4 Security"]
    H4 --> H5["H5 Governance + audit"]
    H5 --> H6["H6 Runtime + cost"]
    H6 --> H7["H7 Governed outcome"]
    H2 -. private first pass .-> L["Ollama local"]
    H3 -. independent review .-> C["Codex / Claude / cloud API"]

Control Panel hiện có bốn bề mặt chính:

Màn hình	Dùng khi nào	Có ghi/sửa source code không?
Ask CASAN	Hỏi tài liệu, kiến trúc, bằng chứng, trạng thái hệ thống	Không; read-only
Goal orchestrator	Đưa một mục tiêu để local worker và cloud reviewer cùng lập lời giải	Không; tạo kết quả và audit, chưa tự sửa workspace
Run observability	Xem một input đã đi qua H1–H7 và dừng/cảnh báo ở đâu	Không
Settings / Approvals	Quản trị cấu hình và quyết định có kiểm soát	Chỉ các action đã đăng ký và đủ quyền

Điểm quan trọng: bạn có thể dùng ba luồng trên hoàn toàn trong trình duyệt, không cần mở Codex, VS Code hay Claude Code. Tuy nhiên, phiên bản hiện tại chưa có “workspace executor” được cấp quyền tự tạo/sửa source code từ Goal orchestrator. Kết quả của Goal orchestrator là kế hoạch/lời giải đã được hai model kiểm tra. Bước ghi code vẫn phải đi qua một action có approval hoặc một coding agent bên ngoài.

2. Chuẩn bị một lần

Kiểm tra các thành phần sau:

docker version
docker compose version
codex --version
claude --version
curl -fsS http://localhost:20128/v1/models

Model local mặc định hiện dùng Ollama ở host.docker.internal:11434. OmniRoute có Dashboard tại http://localhost:20128 và API base http://localhost:20128/v1.

Không ghi API key vào Git, file Markdown hay biến build frontend. API key chỉ nhập qua màn hình Model connections; backend mã hóa theo tenant trước khi lưu.

3. Khởi động toàn bộ local stack

Từ thư mục gốc repository:

packages/casan-harness/scripts/bash/local-full.sh start
packages/casan-harness/scripts/bash/local-full.sh status
packages/casan-harness/scripts/bash/local-full.sh verify

Các địa chỉ chính:

Control Panel: https://localhost:18443
Dashboard hạ tầng: http://127.0.0.1:18080
MinIO Console: http://127.0.0.1:19091
OmniRoute: http://localhost:20128

Local Control Panel dùng chứng chỉ self-signed. Lần đầu, mở URL bằng trình duyệt và chấp nhận chứng chỉ local thủ công. Không dùng cách bỏ qua cảnh báo chứng chỉ cho production.

Khi cần dừng:

packages/casan-harness/scripts/bash/local-full.sh stop

Lệnh stop xóa bridge token. Lần start tiếp theo sinh token mới.

4. Kết nối model

4.1 Tài khoản Codex hoặc Claude

Mở Ask CASAN.
Chọn Manage model connections.
Trong Local account connector, xem trạng thái Codex và Claude.
Nếu chưa đăng nhập, chọn Login. Browser login chính thức của CLI sẽ mở và redirect theo cơ chế của Codex/Claude.
Control Panel chỉ nhận trạng thái đã được làm sạch. Credential OAuth vẫn thuộc CLI trên Mac, không nằm trong browser hoặc container.

Goal orchestrator ưu tiên một tài khoản cloud đã đăng nhập. Nếu cả hai sẵn sàng, Claude được ưu tiên làm reviewer; nếu Claude chưa đăng nhập thì dùng Codex. Nếu account connector không sẵn sàng, hệ thống mới dùng cloud/gateway connection đã cấu hình.

4.2 Ollama local

Trong Model connections:

Chọn Ollama Local.
Endpoint local Docker: http://host.docker.internal:11434.
Chọn Refresh để tải danh sách model.
Đặt model mặc định, ví dụ ornith:9b.

4.3 OmniRoute hoặc cloud API key

Với OmniRoute:

Endpoint: http://host.docker.internal:20128/v1
Model được lấy từ /models.
OmniRoute là fallback khi account connector không dùng được.

Với OpenAI/Anthropic API:

Chỉ dùng endpoint chính thức được allowlist.
API key được gửi thẳng tới backend qua HTTPS local và lưu mã hóa theo tenant.
UI không đọc lại hoặc hiển thị key đã lưu.

5. Case 1 — Hỏi hệ thống mà không cần IDE

Mở Ask CASAN, chọn model và hỏi:

Hạ tầng local hiện có những thành phần nào, phần nào chưa có bằng chứng chạy thật?

CASAN sẽ:

phân loại prompt;
chỉ đọc nguồn nằm trong allowlist;
chạy security scan input/output;
trả câu trả lời có source;
ghi audit và telemetry.

Sau khi có câu trả lời, chọn Open live H1–H7 trace để xem đường đi.

6. Case 2 — Chỉ đưa mục tiêu, local và cloud cùng giải quyết

Mở Goal orchestrator và nhập một mục tiêu, ví dụ:

Lập kế hoạch đưa ứng dụng OKR hiện tại lên production, có rollback, theo dõi lỗi và tiêu chí nghiệm thu rõ ràng.

Luồng thực tế:

H1 kiểm tra hợp đồng mục tiêu và độ dài.
H4 quét mục tiêu trước khi đưa cho model.
Ollama local tạo phương án đầu tiên.
Output local được quét lại.
Codex/Claude account hoặc cloud connection phản biện và viết kết quả cuối.
Kết quả cuối được H4 quét lần nữa.
H5 tạo audit hash; H6 ghi runtime/token; H7 kết thúc.

Trạng thái có ý nghĩa như sau:

completed: local và cloud đều đóng góp thành công;
degraded: local thành công nhưng cloud/gateway không sẵn sàng; kết quả local được giữ lại và cảnh báo rõ;
failed: security hoặc local worker không cho phép tiếp tục.

7. Case 3 — Tìm chính xác input bị dừng ở đâu

Có hai cách mở Trace Explorer:

từ nút Open live H1–H7 trace sau câu trả lời;
từ Run observability, chọn Open H1–H7 ở một run.

Mỗi H có thể click để xem:

trạng thái mới nhất;
lý do pass/warning/blocked/error;
thời gian;
evidence an toàn như model, token, latency, hash và decision.

Trace không đưa raw prompt, API key hoặc credential vào evidence.

8. Thêm một app mới trong cùng workspace

Không cần di chuyển app OKR đang có. Với app độc lập, tạo domain pack riêng thay vì trộn yêu cầu vào apps/okr:

apps/<app-slug>/
├── domain/
│   ├── input/          # yêu cầu nguồn
│   ├── corpus/         # tài liệu dùng làm evidence
│   └── golden-runs/    # case chuẩn để đánh giá
├── config/             # cấu hình riêng của app
├── src/                # code riêng nếu app dùng cấu trúc package
└── test/               # test riêng

Sau đó thêm project vào packages/casan-harness/config/project-registry.json với domain_root trỏ tới apps/<app-slug>/domain, rồi chạy:

packages/casan-harness/scripts/bash/verify-harness-reuse.sh

Không làm các việc sau:

đặt yêu cầu app mới trong apps/okr/domain/input;
dùng chung secret hoặc state giữa hai tenant/project;
sửa gate H1–H7 chỉ để một app mới pass;
copy toàn bộ harness vào app mới.

9. Khi nào cần máy Linux `192.168.1.5`

Giữ Control Panel và account connector trên Mac trong giai đoạn local. Dùng máy Linux khi cần:

chạy model hoặc workload nặng;
thử Docker/Kubernetes gần production hơn;
chạy worker riêng trong LAN;
kiểm tra backup/restore hoặc benchmark.

Không copy credential Codex/Claude từ Mac sang Linux. Với production, dùng API credential trong Vault/KMS hoặc workload identity, không dùng developer browser login.

10. Troubleshooting nhanh

Control Panel không mở

packages/casan-harness/scripts/bash/local-full.sh status
docker compose -f docker-compose.control-panel.local.yml ps
docker logs --tail 100 output_casan5_refined-control-panel-api-1

codex login status
claude auth status --json
curl -fsS http://127.0.0.1:20130/healthz

Nếu CLI chưa login, thực hiện login từ Control Panel hoặc CLI chính thức. Không copy token vào cấu hình CASAN.

Goal dừng ở `degraded`

Mở H3 trong Trace Explorer. Các nguyên nhân thường gặp:

account CLI chưa login;
account model bridge bận hoặc rate limited;
OmniRoute/provider đang unavailable;
cloud preflight chặn dữ liệu nhạy cảm.

Kết quả degraded không được trình bày như kết quả hai-model hoàn chỉnh.

Trace cũ chỉ có một H

Đó là legacy trace được sinh trước khi event schema H1–H7 được thêm. Các chat/goal mới tự động có event chi tiết.

11. Checklist trước khi dùng hàng ngày

local-full.sh verify pass.
Ollama connected và có default model.
Ít nhất Codex/Claude account hoặc một cloud connection sẵn sàng.
Một Goal smoke có local worker và cloud reviewer đều pass.
Trace của smoke đạt 7/7.
Không có API key trong Git diff.
Chưa dùng cấu hình local này như production.

10 KiB Raw Permalink Blame History Unescape Escape