Phát triển tại các điểm mở rộng
DX-OS giữ nghiệp vụ phổ biến trong tệp mô hình và để logic đặc thù ở ngoài lõi. Tài liệu này hướng dẫn nối dịch vụ, bên nhận sự kiện và giao diện riêng vào hệ thống đang chạy mà không đưa tên thực thể, vai hay luồng của một lĩnh vực vào mã lõi.
Mức hỗ trợ hiện tại
Trong tài liệu này, ổn định nghĩa là hợp đồng đã có tài liệu và kiểm tra trong repository. Nó không có nghĩa một mô hình có thể đổi trường mà mã tích hợp không cần kiểm tra lại. Thử nghiệm nghĩa là cách làm chạy được trong source tree hiện tại nhưng chưa có ranh giới cài đặt hoặc nâng cấp được bảo toàn.
| Nhu cầu | Mức hỗ trợ | Ranh giới nâng cấp |
|---|---|---|
| Dịch vụ riêng gọi API của lõi | Ổn định | Dùng client riêng cho đúng một vai của một mô hình và đọc OpenAPI sinh từ mô hình đang chạy |
| Bên nhận phản ứng sau thay đổi | Ổn định | Webhook có chữ ký, schemaVersion và API đọc bù; chặn một hành động trước khi trạng thái đổi dùng khóa check của hành động |
| Giao diện ngoài chạy ở origin riêng | Ổn định | Đăng ký public client bằng dxos client browser add; redirect và CORS dùng danh sách chính xác, không nhận wildcard |
| Trang hoặc thành phần form trong web Tầng 2 | Tùy biến source | Phải sửa và dựng lại image frontend; chưa có registry plugin hay kiểm tra tương thích |
| Route riêng dưới gateway DX-OS | Ổn định | deploy/apisix/local.yaml của bản cài được kiểm và ghép với cấu hình lõi; giữ nguyên khi nâng cấp |
| Quy trình riêng | Ổn định bằng khai báo | Khai báo states và actions trong tệp mô hình, không viết plugin; xem Viết tệp mô hình |
Ưu tiên tệp mô hình và API chung trước khi viết mã. Một dịch vụ chỉ gọi API DX-OS không cần thêm route vào APISIX của DX-OS.
Nguyên tắc chung
- Giữ mã mở rộng trong repository, image và vòng đời phát hành riêng.
- Dùng client hẹp nhất: một ứng dụng máy giữ đúng một vai của một mô hình; trình duyệt dùng đăng nhập người dùng với Authorization Code và PKCE.
- Không đưa secret vào image, repository, biến build frontend, URL, log hoặc lệnh có thể nằm trong shell history.
- Gửi
Idempotency-Keycho thao tác tạo hồ sơ và hành động có thể được thử lại. - Chấp nhận trường JSON mới, nhưng từ chối
schemaVersionchưa hỗ trợ và kiểm lại OpenAPI sau mỗi lần đổi mô hình. - Ghi và truyền
X-Request-Idđể đối chiếu log gateway, dịch vụ mở rộng và backend. - Tách lỗi của phần mở rộng khỏi lõi bằng timeout, hàng đợi hoặc retry có giới hạn; không giữ một request của người dùng để chờ công việc dài.
Dịch vụ riêng gọi API
Đây là đường mở rộng phù hợp khi cần tính toán, đồng bộ hoặc giao tiếp với một hệ thống khác nhưng dữ liệu và chuyển trạng thái vẫn do DX-OS quản lý.
1. Chọn hợp đồng và quyền
Áp dụng mô hình trước, rồi chọn một vai có đúng quyền mà dịch vụ cần.
Quản trị viên đăng ký ứng dụng ở tab Ứng dụng ngoài của /console hoặc bằng lệnh:
dxos client add equipment-sync --model equipment --role KEEPER
Kết quả có clientId và secret; secret chỉ hiện lần này.
Lưu secret vào trình quản lý secret hoặc một tệp chỉ tiến trình dịch vụ đọc được, không chép vào .env của source tree.
Mỗi client giữ đúng một vai của một mô hình.
API của mô hình khác, API quản trị và API người dùng trả 403.
Đổi sang vai khác của cùng mô hình bằng dxos client role <tên> --role <vai> hoặc nút Đổi vai ở tab Ứng dụng ngoài; client id và secret giữ nguyên, còn token đã cấp giữ vai cũ đến khi hết hạn.
Đổi sang mô hình khác thì xóa client rồi đăng ký lại; hồ sơ client đã tạo vẫn còn.
2. Lấy token và OpenAPI của mô hình
Ví dụ dưới đây giữ secret trong tệp có quyền 600 và không đặt giá trị secret trên dòng lệnh:
export DXOS_BASE_URL=https://dxos.example.org
export DXOS_CLIENT_ID=dxos-app-equipment-sync
export DXOS_SECRET_FILE=/run/secrets/dxos-client-secret
TOKEN="$(curl -fsS \
--data-urlencode grant_type=client_credentials \
--data-urlencode "client_id=$DXOS_CLIENT_ID" \
--data-urlencode "client_secret@$DXOS_SECRET_FILE" \
"$DXOS_BASE_URL/realms/dxos/protocol/openid-connect/token" | jq -r .access_token)"
curl -fsS \
-H "Authorization: Bearer $TOKEN" \
"$DXOS_BASE_URL/api/v1/meta/models/equipment/openapi" \
-o equipment.openapi.json
OpenAPI này được sinh từ phiên bản mô hình đang chạy và chỉ chứa các thực thể người gọi được đọc. Dùng nó để sinh client hoặc làm đầu vào cho kiểm thử hợp đồng; không sao chép một schema cũ vào mã rồi coi đó là nguồn thật.
3. Gọi dữ liệu và quy trình
API dữ liệu nằm dưới /api/v1/data/{model}/{entity}.
Trường, hành động, mã lỗi và dữ liệu bắt buộc của mỗi hành động nằm trong OpenAPI vừa lấy; tổng quan ở API.
curl -fsS \
-H "Authorization: Bearer $TOKEN" \
"$DXOS_BASE_URL/api/v1/data/equipment/loan?page=0&size=20"
Khi tạo hồ sơ hoặc gọi hành động, sinh một khóa ổn định cho chính yêu cầu nghiệp vụ và gửi ở header Idempotency-Key.
Gửi lại cùng khóa và cùng nội dung nhận lại kết quả đầu; dùng cùng khóa cho nội dung khác trả 409.
Khi sửa hồ sơ, gửi version đã đọc và xử lý ERR_CONCURRENT_MODIFICATION thay vì ghi đè.
Không ghi trực tiếp PostgreSQL và không đổi cột status qua API dữ liệu.
Mọi chuyển trạng thái đi qua /actions/{action} để các quy tắc, Flowable, lịch sử và sự kiện cùng được áp dụng.
4. Chạy local và kiểm thử
Chạy dịch vụ ngoài Compose của lõi với DXOS_BASE_URL=http://localhost:9080.
Kiểm ít nhất các tình huống sau:
- Lấy token, tải OpenAPI và gọi một endpoint được vai cho phép.
- Gọi mô hình khác hoặc endpoint quản trị và nhận
403. - Gửi lại một yêu cầu có cùng
Idempotency-Keymà không tạo tác dụng lần hai. - Mô phỏng token hết hạn,
429, timeout và409mà không retry vô hạn. - Đổi tên hoặc bỏ trường trong bản mô hình thử và để kiểm thử hợp đồng chỉ ra chỗ tích hợp phải đổi.
examples/itot-simulator minh họa dịch vụ ngoài lấy token máy, tạo hồ sơ, thực hiện hành động và chống gửi trùng.
Lệnh setup của ví dụ tự gọi Keycloak để ví dụ chạy độc lập; bản triển khai thật dùng dxos client add để client xuất hiện trong quản trị và danh mục dữ liệu.
5. Đóng gói và nâng cấp
Đóng gói dịch vụ thành image riêng, chạy bằng Compose hoặc hệ điều phối riêng và truyền URL, client id, secret bằng cấu hình lúc chạy.
Không thêm service vào deploy/docker-compose.yml của bộ cài nếu muốn dxos update không ghi đè phần triển khai riêng.
Trước khi nâng DX-OS hoặc áp dụng phiên bản mô hình mới:
- Lấy OpenAPI từ môi trường thử và so với hợp đồng mà dịch vụ đang dùng.
- Chạy lại các kiểm thử quyền, idempotency, lỗi đồng thời và timeout.
- Triển khai dịch vụ tương thích trước khi áp dụng thay đổi phá vỡ hợp đồng.
- Xoay secret bằng
dxos client rotate <tên>và cập nhật secret runtime; token cũ có thể dùng tới khi hết hạn, khoảng 5 phút. - Gỡ client không còn dùng bằng
dxos client remove <tên>.
Bên nhận webhook
Webhook phù hợp cho thông báo, đồng bộ bất đồng bộ, lập chỉ mục hoặc kích hoạt công việc sau khi DX-OS đã ghi thay đổi.
Webhook không từ chối được hành động; muốn dịch vụ riêng chặn một hành động trước khi trạng thái đổi thì dùng check ở hành động, xem Kiểm tra trước khi chuyển trạng thái.
1. Khai báo đích
Đặt cấu hình của bản cài trong deploy/webhooks/targets.yml, ngoài git:
targets:
extension_worker:
url: https://worker.example.org/dxos/events
secret: <một bí mật ngẫu nhiên>
format: json
Tệp mô hình chọn đích bằng khóa ở đầu tệp:
webhook: extension_worker
Chi tiết nạp lại cấu hình, retry, thứ tự và payload nằm ở Tích hợp với hệ thống ngoài.
2. Xử lý an toàn
Bên nhận thực hiện theo thứ tự:
- Đọc nguyên văn byte của body và kiểm
X-Dxos-Signaturebằng HMAC-SHA256 với phép so constant-time. - Từ chối
schemaVersionchưa hỗ trợ; với phiên bản đã biết, bỏ qua trường mới mà nó chưa dùng. - Ghi bền vững
eventIdtrước khi trả2xx; nếu nhận lại id đã có thì trả2xxmà không làm lại tác dụng. - Đưa công việc dài sang hàng đợi riêng và trả lời trong 5 giây.
- Chỉ gọi lại API dữ liệu khi cần nội dung hồ sơ, bằng client có quyền hẹp phù hợp.
record.event và admin.event có dãy eventId riêng.
Bên nhận xử lý cả hai loại phải khử trùng theo cặp loại thông điệp và eventId.
3. Chạy local và đọc bù
URL webhook phải truy cập được từ container backend.
Trên Docker Desktop có thể dùng host.docker.internal; trên Linux, chạy bên nhận trong một mạng Docker mà backend tới được hoặc dùng một địa chỉ thử nghiệm riêng.
Để kiểm:
- Tạo hoặc sửa một hồ sơ và xác nhận bên nhận lưu đúng một lần.
- Trả mã lỗi để thấy thông điệp ở tab Hàng đợi sự kiện, sau đó khôi phục bên nhận và bấm Thử lại.
- Gửi lại cùng payload để chứng minh
eventIdđược khử trùng. - Sửa một byte của body và xác nhận chữ ký bị từ chối.
Bên nhận lỡ tin đọc bù từng trang bằng GET /api/v1/events?after=<eventId>&size=500 và tiếp tục khi more là true.
Feed này yêu cầu ADMIN; client tạo bằng dxos client add không được cấp vai nền tảng này.
Thay đổi của quản trị đọc bù bằng GET /api/v1/events/admin với cùng quy ước after, size, next và more.
Giữ cursor chỉ sau khi toàn bộ trang đã được lưu thành công.
examples/history-witness minh họa đọc hết các trang, giữ eventId cùng hash ở ngoài máy chủ và so lại về sau.
4. Đóng gói và nâng cấp
Đóng gói receiver tách khỏi DX-OS, giữ secret trong secret runtime và sao lưu kho khử trùng cùng cursor.
Theo dõi schemaVersion, kiểm payload thử trước khi nâng và triển khai receiver chấp nhận cả phiên bản cũ lẫn mới trong khoảng chuyển tiếp khi hợp đồng thay đổi.
Giao diện ngoài
Giao diện trình duyệt phải đăng nhập người dùng bằng Authorization Code và PKCE.
Không đặt client secret hoặc dùng client_credentials trong JavaScript gửi tới trình duyệt.
Đăng ký client và origin
Ví dụ giao diện phục vụ ở https://partner.example và nhận callback tại /auth/callback:
dxos client browser add partner-ui \
--redirect-uri https://partner.example/auth/callback
Lệnh tạo public client dxos-browser-partner-ui, bật Authorization Code với PKCE S256, thêm mapper audience dxos-api và claim nhóm, rồi thêm https://partner.example vào CORS_ALLOWED_ORIGINS trong deploy/.env.
Nếu backend đang chạy, lệnh tạo lại riêng backend và chờ service sẵn sàng.
Nêu nhiều --redirect-uri khi ứng dụng có callback và silent renew riêng; mỗi URI được giữ chính xác, không tự mở rộng bằng wildcard.
Ứng dụng dùng:
| Giá trị OIDC | Cấu hình |
|---|---|
| Authority | http://localhost:9080/realms/dxos |
| Client id | dxos-browser-partner-ui |
| Flow | Authorization Code + PKCE |
| Redirect và post-logout URI | Một URI chính xác đã đăng ký |
| Scope | openid profile |
Thay authority bằng địa chỉ gateway thật khi triển khai. Không đặt secret trong giao diện; client public không có secret.
Redirect ngoài máy phát triển phải dùng HTTPS; HTTP chỉ nhận localhost, 127.0.0.1 hoặc [::1].
Wildcard, user info, fragment, host hoặc cổng sai bị từ chối trước khi thay Keycloak.
CORS_ALLOWED_ORIGINS chỉ chứa các origin cách nhau bằng dấu phẩy, không có path, query hay dấu / cuối; backend kiểm lại khi khởi động và dxos doctor báo trước giá trị sai.
Sau đăng nhập, gửi access token ở Authorization: Bearer <token> và đọc /api/v1/meta/models/{model}/openapi bằng chính người dùng đó.
Tài liệu sinh ra chỉ chứa thực thể người dùng được xem, nên giao diện vẫn phải xử lý 403 khi quyền đổi và không tự suy quyền từ nút đang hiển thị.
Kiểm luồng đăng nhập, callback, refresh hoặc đăng nhập lại khi token hết hạn, single logout, 401, 403 và việc quay về đúng trang ban đầu.
Liệt kê bằng dxos client browser list và gỡ bằng dxos client browser remove partner-ui.
Lệnh gỡ giữ origin trong CORS_ALLOWED_ORIGINS vì client khác có thể dùng chung; quản trị viên xóa origin không còn dùng rồi tạo lại backend.
Phục vụ giao diện dưới cùng gateway vẫn cần route riêng, chịu giới hạn của phần Route riêng trong APISIX.
Trang riêng trong web Tầng 2
Trước hết kiểm tra khối ui: của tệp mô hình có đáp ứng được menu, cột, biểu mẫu, gợi ý, lịch và thống kê hay không.
Đường khai báo này được giữ khi nâng cấp và không cần dựng lại frontend.
Nếu vẫn cần trang riêng, hiện chỉ có cách tùy biến source:
- Tạo component dưới
frontend/src/và nạp chậm nếu trang lớn. - Thêm
<Route>trong<CustomRoutes>và mụcMenu.Itemtương ứng ởfrontend/src/admin/AdminApp.tsx. - Dùng
frontend/src/shell/api.tsđể request mang token và giữ kiểm tra quyền ở backend. - Chạy
npm cirồinpm run buildtrongfrontend/. - Ở môi trường source, dựng và thay riêng image bằng
cd deploy && docker compose build frontend && docker compose up -d --no-deps frontend.
Đóng gói frontend tùy biến bằng image và tag riêng.
dxos update kéo image frontend chính thức, còn nâng bộ cài thay các tệp runtime; do đó đội sở hữu bản tùy biến phải rebase thay đổi, chạy lại build và phát hành lại image sau mỗi phiên bản.
Chưa có registry cho trang hay thành phần form, chưa có sandbox và chưa có kiểm tra tương thích plugin. Không tải JavaScript tùy ý từ mô hình hoặc từ một URL do người dùng nhập.
Route riêng trong APISIX
Dịch vụ chỉ gọi DX-OS không cần route này. Chỉ thêm route khi người dùng hoặc hệ thống khác phải gọi dịch vụ mở rộng qua cùng cổng vào.
Tạo deploy/apisix/local.yaml trong bản cài từ local.example.yaml; file này chỉ chứa phần bổ sung, còn common.yaml do lõi quản lý.
Ví dụ sau giả định container extension-worker cùng mạng Docker với APISIX:
upstreams:
- id: extension-worker
type: roundrobin
nodes:
"extension-worker:8080": 1
routes:
- id: extension-worker-api
uri: /extensions/worker/*
upstream_id: extension-worker
plugin_config_id: bearer-token
File local nhận upstreams, routes và tùy chọn public_routes, trong một tài liệu YAML tối đa 1 MiB, không khóa trùng, anchor hay alias.
Route phải có id riêng, tham chiếu hợp lệ và priority lớn hơn -10 của web fallback (mặc định 0).
Đường dẫn của route local không được giao với route lõi hay route local khác, trừ web fallback /*; đường có %, đoạn . hoặc .., dấu gạch chéo kép và ký tự điều khiển bị từ chối.
Host, methods và priority không cho phép ghi đè đường dẫn của lõi, kể cả khi thành phần tương ứng tắt trong chế độ core.
APISIX chuyển nguyên đường dẫn /extensions/worker/... tới dịch vụ.
bearer-token xác thực token; dịch vụ mở rộng vẫn phải kiểm quyền nghiệp vụ.
Route public khai tường minh public_routes: {<id>: "lý do công khai"} trong file local; id phải thuộc một route local không kiểm token.
Metadata này chỉ phục vụ kiểm cấu hình, không được nạp thành resource APISIX.
Kiểm và nạp lại từ thư mục deploy của bản cài:
docker compose run --rm --no-deps apisix-config --check
docker compose run --rm --no-deps apisix-config
Trình kiểm dùng cùng image APISIX đã ghim với gateway, không cần cài Python trên máy triển khai.
Trong source tree chạy được python3 e2e/api/check_routes.py --local <tệp> (cần Python, PyYAML và Docker; thêm --mode core hoặc --admin-console để kiểm cấu hình tương ứng).
Cấu hình hợp lệ được ghép theo thứ tự lõi rồi local và thay tệp đầu ra nguyên tử, APISIX đang chạy tự đọc lại.
Lỗi schema, plugin, tham chiếu hoặc xung đột giữ tệp đầu ra hợp lệ trước đó và chỉ nêu tệp, resource và loại lỗi.
Sau khi thay container upstream, chạy docker compose restart apisix để làm mới địa chỉ.
dxos update giữ nguyên tệp local và kiểm nó với common.yaml mới trước khi thay container.
Xung đột với bản lõi mới làm cập nhật dừng để người triển khai sửa local; bước nâng bộ cài có thể đã thay các tệp runtime, nên đây không phải hoàn tác toàn bộ.
Bỏ tệp local rồi nạp lại để gỡ các route riêng.
Cất bản sao tệp local cùng cấu hình triển khai, vì sao lưu Postgres và SeaweedFS không chứa tệp này.