Chuyển tới nội dung chính

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ầuMức hỗ trợRanh giới nâng cấp
Dịch vụ riêng gọi API của lõiỔn địnhDù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 địnhWebhook 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 2Tùy biến sourcePhả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 địnhdeploy/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áoKhai 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-Key cho 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 schemaVersion chư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-Key mà không tạo tác dụng lần hai.
  • Mô phỏng token hết hạn, 429, timeout và 409 mà 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:

  1. Lấy OpenAPI từ môi trường thử và so với hợp đồng mà dịch vụ đang dùng.
  2. Chạy lại các kiểm thử quyền, idempotency, lỗi đồng thời và timeout.
  3. Triển khai dịch vụ tương thích trước khi áp dụng thay đổi phá vỡ hợp đồng.
  4. 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.
  5. 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ự:

  1. Đọc nguyên văn byte của body và kiểm X-Dxos-Signature bằng HMAC-SHA256 với phép so constant-time.
  2. Từ chối schemaVersion chưa hỗ trợ; với phiên bản đã biết, bỏ qua trường mới mà nó chưa dùng.
  3. Ghi bền vững eventId trước khi trả 2xx; nếu nhận lại id đã có thì trả 2xx mà không làm lại tác dụng.
  4. Đưa công việc dài sang hàng đợi riêng và trả lời trong 5 giây.
  5. 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ị OIDCCấu hình
Authorityhttp://localhost:9080/realms/dxos
Client iddxos-browser-partner-ui
FlowAuthorization Code + PKCE
Redirect và post-logout URIMột URI chính xác đã đăng ký
Scopeopenid 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:

  1. Tạo component dưới frontend/src/ và nạp chậm nếu trang lớn.
  2. Thêm <Route> trong <CustomRoutes> và mục Menu.Item tương ứng ở frontend/src/admin/AdminApp.tsx.
  3. Dùng frontend/src/shell/api.ts để request mang token và giữ kiểm tra quyền ở backend.
  4. Chạy npm ci rồi npm run build trong frontend/.
  5. Ở 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.