Signet
🇻🇳 Tiếng Việt | 🇬🇧 English
Lõi nền tảng nguồn mở, tự cài, đóng dấu tin cậy lên mọi thứ đi qua nó — kèm ứng dụng đầu tiên chạy trên lõi: Văn phòng điện tử quản lý văn bản đến, văn bản đi theo Nghị định 30/2020/NĐ-CP.
Sản phẩm dự thi Olympic Tin học Sinh viên Việt Nam 2026 — nội dung Phần mềm Nguồn mở (OLP PMNM 2026), chủ đề DX-OS Open-Core.
Dùng thử: https://signet.htechcs.com (bản phát hành mới nhất kèm vài bản vá, xem Chạy thử) · tự cài trên máy mình bằng bốn lệnh ở Cài đặt từ mã nguồn.
Xem nhanh 5 phút, tìm tài liệu theo từng phần: docs/README.md · trang tài liệu
https://hit-champion.github.io/Signet/.
Đọc nhanh: Giới thiệu · Kiến trúc · Tính năng · 4 nguyên lý · Công nghệ · Cài đặt · Chạy thử · Vận hành · Sự cố · Tài liệu · Liên hệ · Giấy phép
Giới thiệu
Signet là chiếc nhẫn ấn xưa dùng để đóng dấu lên thư từ, văn bản: nhìn dấu biết ai gửi, niêm còn nguyên biết chưa ai mở hay sửa. Lõi Signet làm đúng việc đó cho dữ liệu số.
Hơn 900.000 doanh nghiệp nhỏ và vừa cùng các trường, khoa, cơ quan cấp cơ sở đang chuyển đổi số bằng cách mua nhiều phần mềm rời rạc (dữ liệu thành ốc đảo) hoặc một hệ thống nguyên khối (thành "con tin" của nhà cung cấp, mất chủ quyền số). Đằng nào thì mỗi ứng dụng mới cũng dựng lại từ đầu phần đăng nhập, lưu tệp, phân quyền, quy trình duyệt — và tự lo phần tin cậy, mà thường là không lo.
Signet tách phần dùng chung đó thành một lõi chạy ngầm, không giao diện, lắp hoàn toàn từ phần mềm nguồn mở để tổ chức tự cài, tự làm chủ. Ứng dụng mới chỉ cần cắm vào lõi là có sẵn bốn con dấu tin cậy, không phải tự làm:
| Con dấu | Nghĩa là | Thành phần | Cụm Tầng 1 |
|---|---|---|---|
| Biết ai đã làm | Mọi lời gọi mang danh tính SSO, kể cả của tác tử AI; vai trò quan trọng bắt buộc xác thực hai bước | Keycloak, APISIX | ① ② |
| Sạch | Tệp được quét mã độc trước khi lưu, tệp bẩn không chạm tới kho | svc-files + ClamAV | ① |
| Không sửa lén được | Mọi thay đổi vào sổ kiểm toán chuỗi băm; mốc đầu chuỗi neo ra ngoài CSDL, sửa lén thì make audit chỉ ra dòng bị sửa | PostgreSQL, schema core | ⑥ |
| Kiểm chứng được từ bên ngoài | Văn bản phát hành mang mã QR, SHA-256 và chữ ký số (minh họa, không có giá trị pháp lý); cổng xác thực công khai, không cần đăng nhập | svc-files, route /api/verify | ④ ⑥ |
Kiến trúc
Signet theo khung ba tầng của đề DX-OS:
- Tầng 1 — lõi không giao diện: định danh, cổng API, dữ liệu có cấu trúc và phi cấu trúc, quy trình, lớp tin cậy
(bảy cụm ①–⑦,
docs/architecture.md§3). Không có màn hình nghiệp vụ; ứng dụng gọi lõi qua cổng. - Tầng 2 — bốn không gian H-P-D-I có giao diện (bảng dưới). Văn phòng điện tử là một ứng dụng web nhưng có màn ở
cả bốn không gian; phần máy chủ của nó hiện còn chạy chung tiến trình với dịch vụ lõi (ranh giới và hướng tách:
docs/architecture.md§4). Không gian cá nhân P.A.R.A không sửa mã dịch vụ lõi, nhưng được thêm tay vào cấu hình lõi (client Keycloak, route ở cổng, bảng và quyền trong CSDL). Bảng tin đơn vị và Đơn nghỉ phép cắm vào bằng một lệnhmoc app installmà không sửa tệp nào của lõi (docs/them-ung-dung.md). - Tầng 3 — ứng dụng ngành (bán hàng, kho, học tập, quan hệ khách hàng…): đề không bắt buộc. Ứng dụng đầu tiên là
Đổi, bù lịch giảng (
apps/lich-giang): giảng viên đề nghị, trưởng bộ môn rồi lãnh đạo đơn vị duyệt trên quy trình của lõi; cắm vào như Bảng tin, bằngmoc app install.
| Không gian | Màn hình, ứng dụng ở Tầng 2 |
|---|---|
| [H] Con người | Không gian cá nhân P.A.R.A (tệp của từng người), Bảng tin đơn vị, trang Ứng dụng của Văn phòng; wiki DokuWiki (profile wiki). Đăng nhập một lần, vai trò, đơn vị lấy từ Keycloak ở Tầng 1 |
| [P] Quy trình | Văn phòng điện tử: tiếp nhận, văn bản đến, văn bản đi, hộp việc và Lịch hạn, sổ đăng ký; Đơn nghỉ phép; trang Dựng form cho quản trị |
| [D] Dữ liệu | Văn phòng điện tử: Điều hành, Số đo, Phả hệ số liệu, Sơ đồ cảm biến, Sổ kiểm toán, Hồ sơ công việc (nộp lưu sang kho lạnh, phòng đọc), trang Trạng thái báo tuổi hai nguồn dữ liệu công khai (/trang-thai); trang Tài liệu API (REST, GraphQL) |
| [I] Trí tuệ | Văn phòng điện tử: Tìm kiếm toàn văn, Hỏi đáp (tìm theo từ khóa và theo nghĩa), gợi ý ô khi tiếp nhận văn bản đến, gợi ý giao việc |
Chỉ cổng APISIX mở ra ngoài, mọi yêu cầu qua tường lửa ứng dụng web ở đó trước khi tới lõi; nhãn trên mũi tên là đường dẫn thật. Bên trong máy cũng vậy:
- container ứng dụng ở mạng Docker riêng
apps(không ra Internet), nơi dịch vụ lõi duy nhất là APISIX; - vì thế phần máy chủ của ứng dụng cũng gọi lõi qua cổng, qua cùng bước kiểm token, giới hạn tốc độ, WAF như trình duyệt;
make demo-cai-ung-dungkiểm container chỉ tới được APISIX (docs/them-ung-dung.mdmục 1.4).
Viền đậm là mã của đội, hộp có logo là phần mềm nguồn mở dùng nguyên bản, chấm sáng đi theo hai yêu cầu thật. Kiến trúc
H-P-D-I và các quyết định kỹ thuật: docs/architecture.md.
Tính năng
Văn phòng điện tử
Ở khoa, trường và các cơ quan nhỏ, công văn vẫn đến bằng giấy hoặc bản scan gửi qua email, Zalo; văn thư ghi sổ tay hoặc Excel; lãnh đạo bút phê trên giấy. Trên Signet, một công văn đi trọn vòng đời tiếp nhận → vào sổ → chỉ đạo → xử lý → trả lời → phát hành → lưu trữ theo Nghị định 30/2020/NĐ-CP về công tác văn thư:
| Vấn đề hiện nay | Signet xử lý bằng | Không gian |
|---|---|---|
| Văn bản thất lạc, không biết đang nằm ở bàn ai | Vào sổ, luồng xử lý BPMN, hộp việc của đúng người, thông báo tức thời | [P] |
| Quá hạn giải quyết mà không ai nhắc | Hạn theo từng việc được giao, tự nhắc rồi báo lãnh đạo; văn bản khẩn lên đầu | [P] |
| Nhập sai, vào sổ trùng | Chặn nhập sai ở cả form, máy chủ và CSDL theo một JSON Schema dùng chung (Poka-yoke); chặn vào sổ trùng | [P] |
| Văn thư gõ lại từng công văn đến | Tác tử đọc lớp chữ PDF hoặc nhận dạng chữ bản scan, gợi ý sẵn số ký hiệu, ngày, cơ quan, trích yếu | [I] |
| Đơn vị gửi văn bản cho nhau qua email | Liên thông trên cùng bản cài: bên nhận có ngay văn bản đến, tệp trùng từng byte, kèm mã xác thực | [P] |
| Văn bản nhạy cảm bị lộ | Mã hóa từng tệp, chỉ giải mã trong bộ nhớ cho người có tên; bản mở đóng tên người xem lên mọi trang | [P] |
| Lãnh đạo không biết việc nghẽn ở đâu | Dashboard điều hành từ số liệu thật | [D] |
| Tìm lại văn bản cũ mất thời gian | Tìm toàn văn, cả chữ trong tệp PDF đính kèm và bản scan (nhận dạng chữ); trợ lý hỏi đáp trả lời kèm số ký hiệu và trang | [I] |
Ngoài ra: sổ đăng ký văn bản đến, đi đúng mẫu NĐ 30; nhiều đơn vị trên một bản cài, mỗi người chỉ thấy dữ liệu của
đơn vị mình; Văn phòng điện tử có giao diện tiếng Việt và tiếng Anh. Phạm vi và vai trò:
docs/dac-ta-san-pham.md; mức hoàn thiện từng tính năng kèm bằng chứng:
docs/muc-hoan-thien.md.
Không gian cá nhân P.A.R.A
Tệp của mỗi người xếp trong bốn thư mục Dự án · Lĩnh vực · Tài nguyên · Lưu trữ; client Keycloak riêng, gọi lõi qua
cổng như mọi ứng dụng, không sửa mã dịch vụ lõi; bảng, quyền, client và route được thêm tay vào cấu hình lõi
(make demo-ca-nhan).
Cắm thêm ứng dụng bằng một lệnh
python3 scripts/moc.py app install apps/bang-tin/app.yaml đọc manifest của ứng dụng rồi tạo client Keycloak, route
APISIX, container, schema và migration chạy bằng vai trò CSDL riêng của ứng dụng (không có quyền gì trên lõi), bảng và
quyền Hasura, và đăng ký nhận sự kiện văn bản của lõi; không sửa tệp nào của lõi. Chạy lại không tạo gì trùng;
moc app remove gỡ ứng dụng nhưng giữ dữ liệu. Ứng dụng mẫu là Bảng tin đơn vị (apps/bang-tin, /bang-tin/): văn
bản vừa vào sổ, vừa phát hành hiện lên theo sự kiện của lõi, mỗi người chỉ thấy tin của văn bản mình được xem
(make demo-cai-ung-dung). Cách làm, mô hình tin cậy và giới hạn: docs/them-ung-dung.md
mục 1.
Trợ lý AI chạy tại chỗ
AI trong Signet chỉ gợi ý, người quyết định; mặc định mọi thứ chạy trên máy chủ của tổ chức, dữ liệu không ra ngoài.
| Tác tử | Làm gì |
|---|---|
| Đọc văn bản đến | Đọc lớp chữ PDF, hoặc nhận dạng chữ (Tesseract tiếng Việt) nếu là ảnh chụp, bản scan, rồi gợi ý sáu ô của form tiếp nhận kèm độ tin cậy. Số và ngày luôn do quy tắc theo thể thức NĐ 30 quyết, không bao giờ do mô hình. Trên 22 văn bản mẫu: số ký hiệu đúng 20/22, ngày ban hành đúng 22/22 |
| Hỏi đáp trên kho văn bản | Hỏi bằng câu thường ngày, nhận câu trích nguyên văn kèm nguồn "số ký hiệu · tr. n"; chỉ tìm trong văn bản người hỏi được xem, văn bản hạn chế không bao giờ vào chỉ mục |
| Gợi ý giao việc | Văn bản vừa vào sổ thì gợi ý đơn vị chủ trì và hạn xử lý, kèm các văn bản tương tự đã giao làm căn cứ; chạy song song, không chắn việc của lãnh đạo |
| Che thông tin cá nhân | Số CCCD, điện thoại, email, tài khoản ngân hàng bị che trước khi tới mô hình và nhật ký; người có quyền đọc văn bản vẫn thấy số thật |
Cả bốn chạy được không cần mô hình ngôn ngữ, nên CI, máy yếu, máy không có Internet đều chạy. Mô hình cục bộ
(Ollama, Qwen3 1,7B, chạy trên CPU) viết trích yếu và câu trả lời: make ai-model rồi make up-ai. Riêng bước viết
câu trả lời có thể gọi API ngoài chuẩn OpenAI thay Ollama (MOC_ASK_API=openai, tắt mặc định, #430); khi bật, câu hỏi
và tối đa 4 đoạn văn bản làm căn cứ rời máy chủ, đã che số CCCD/CMND, số điện thoại, email, số tài khoản; họ tên và
địa chỉ không được che. Bước nhúng (tìm theo nghĩa) cũng chuyển được ra API ngoài (MOC_EMBED_API=openai, tắt mặc
định, #498); khi bật, mọi đoạn văn bản không hạn chế trong chỉ mục, che như trên, rời máy chủ. Số đo và giới hạn từng
tác tử:
docs/danh-gia-ai.md.
Ảnh chụp màn hình
Chụp tự động trong lượt e2e (make e2e), dữ liệu mẫu hư cấu. Giao diện mặc định tiếng Việt; trang nào của Văn
phòng điện tử, Không gian cá nhân, Bảng tin và Đơn nghỉ phép cũng có bản tiếng Anh.
| Văn thư tải công văn lên, tác tử điền sẵn các ô | Lãnh đạo xem việc nghẽn ở đâu | Người nhận tự kiểm văn bản, không cần đăng nhập |
|---|---|---|
 |  |  |
Bằng chứng 4 nguyên lý
Mỗi nguyên lý thiết kế của đề có màn demo chạy bằng một lệnh, dưới một phút, in từng bước kèm ✓, chạy lại bao
nhiêu lần cũng được — kịch bản trình bày ở docs/demo-script.md.
| Nguyên lý | Màn demo | Lệnh |
|---|---|---|
| (i) Vòng đời và tốc độ dữ liệu | Hồ sơ đã đóng nộp lưu thành gói Parquet + tệp + manifest có băm trên kho lạnh khóa ghi; vẫn tìm thấy, quét mã QR vẫn "khớp"; trên giao diện: lập hồ sơ, lãnh đạo phòng nộp lưu, phòng đọc xem tệp có dấu tên người xem; trang Điều hành có số liệu văn bản đã nộp lưu do DuckDB đếm thẳng trên gói Parquet trong kho lạnh | make demo-nong-lanh |
| (ii) Hội tụ IT/OT | Cảm biến nhiệt độ → NGSI-LD (Scorpio) → vượt ngưỡng thì dựng dự thảo "Báo cáo sự cố" vào luồng văn bản đi | make demo-it-ot |
| (iii) Quản trị dữ liệu | Phả hệ OpenLineage: gói lưu trữ truy ngược về bảng nghiệp vụ và tệp gốc; kiểm số dòng, cột bắt buộc trước khi ghi; mỗi biểu đồ ở trang Điều hành truy về khung nhìn và bảng nguồn (tính từ catalog PostgreSQL), xem đồ thị ở trang Phả hệ số liệu (/pha-he) | make demo-pha-he |
| (iv) Zero-Trust | Kiểm dịch: mọi tệp qua ClamAV trong svc-files trước khi ghi vào kho; tệp EICAR bị từ chối, không lưu, lần chặn vào sổ kiểm toán | make demo-kiem-dich |
| (iv) Zero-Trust | Văn bản hạn chế: tệp mã hóa trong kho, chỉ người có tên mở được, bản mở có dấu tên | make demo-han-che |
| (iv) Zero-Trust | Két bí mật: svc-files, svc-workflow lấy bí mật từ két OpenBao (AppRole), không qua biến môi trường; két tự mở khóa khi khởi động lại | make demo-ket-bi-mat |
| (iv) GitOps | Tự phục hồi: xóa container, reconciler dựng lại theo khai báo trong git | make demo-tu-phuc-hoi |
Các màn nghiệp vụ, cùng cách chạy: make demo-lien-thong (liên thông hai đơn vị), make demo-nap-lo (nạp lô văn bản
đến), make demo-doc-van-ban, make demo-hoi-dap, make demo-giao-viec, make demo-che-pii (trợ lý AI),
make demo-ky-so (ký số, minh họa), make demo-ca-nhan (ứng dụng thứ hai trên cùng lõi), make demo-cai-ung-dung
(cắm ứng dụng thứ ba bằng một lệnh), make demo-quy-trinh (ứng dụng thứ tư mang quy trình riêng, chạy trên động cơ
quy trình của lõi), make demo-tat-van-phong (tắt phần Văn phòng điện tử, lõi vẫn chạy), make demo-log-tap-trung
(log tập trung).
Công nghệ và giấy phép
Signet điều phối phần mềm nguồn mở ở dạng nguyên bản: image chính thức, phiên bản ghim, không sửa mã thượng nguồn.
Bảng đầy đủ (phiên bản, giấy phép, trang chủ): COPYRIGHT.txt; lý do chọn từng thư viện:
DEPENDENCIES.md.
| Không gian | Thành phần | Phiên bản | Giấy phép | Vai trò trong Signet |
|---|---|---|---|---|
| Cổng | Apache APISIX | 3.18.0 | Apache-2.0 | Cổng duy nhất mở ra ngoài: kiểm JWT ở biên, danh sách trắng đường dẫn, giới hạn tốc độ |
| Cổng | Coraza, OWASP CRS (coraza-proxy-wasm) | 3.3.3, 4.14.0 (0.6.0) | Apache-2.0 | Tường lửa ứng dụng web chạy trong APISIX: soi mọi yêu cầu trước khi kiểm token, tải tấn công nhận 403 |
| [H] | Keycloak | 26.7.5 | Apache-2.0 | Đăng nhập một lần, TOTP; vai trò, đơn vị, phòng đưa vào token |
| [H] | DokuWiki | 2026-07-14c | GPL-2.0 | Wiki nội bộ, mỗi đơn vị một không gian, đăng nhập qua Keycloak, tùy chọn (profile wiki) |
| [P] | Flowable | 8.0.0 | Apache-2.0 | Quy trình BPMN văn bản đến, văn bản đi |
| [P] | Centrifugo | 6.9.7 | Apache-2.0 | Thông báo tức thời qua WebSocket, kênh riêng từng người |
| [P] | Node-RED | 5.0.8 | Apache-2.0 | Tự động hóa bằng flow, gọi lõi qua robot của đơn vị, tùy chọn (profile tu-dong) |
| [D] | PostgreSQL | 16 | PostgreSQL | CSDL chính, sổ kiểm toán chuỗi băm |
| [D] | Hasura GraphQL Engine CE | 2.51.0 | Apache-2.0 | GraphQL tự sinh, quyền theo vai trò và đơn vị đến từng dòng |
| [D] | PostgREST | 14.18 | MIT | REST tự sinh (/rest/v1) cho bảng của ứng dụng sinh (schema sinh); cách ly đơn vị bằng RLS của khung |
| [D] | Supabase Studio, postgres-meta | 2026.10.12, 0.100.0 | Apache-2.0 | Người vận hành nền tảng tạo bảng, thêm cột trong sinh (profile studio, chỉ mở trên máy chủ) |
| [D] | SeaweedFS | 4.48 | Apache-2.0 | Kho tệp chuẩn S3, kho lạnh khóa ghi cho hồ sơ nộp lưu |
| [D] | Meilisearch CE | 1.54.3 | MIT | Tìm toàn văn, chỉ mục đoạn của trợ lý hỏi đáp |
| [I] | Ollama, trọng số Qwen3 | 0.35.1 | MIT; trọng số Apache-2.0 | Mô hình ngôn ngữ cục bộ, tùy chọn (profile ai) |
| [I] | Tesseract OCR | 5.5.0 | Apache-2.0 | Nhận dạng chữ trên công văn scan, ảnh chụp |
| Tin cậy | ClamAV | 1.5.4 | GPL-2.0 | Quét mã độc trước khi lưu |
| Tin cậy | OpenBao | 2.7.1 | MPL-2.0 | Két bí mật, khóa mã hóa văn bản hạn chế, CA nội bộ và khóa ký |
| IT/OT | Scorpio Broker, PostGIS | 6.0.2, 16-3.5 | BSD-3-Clause, GPL-2.0 | Bản sao số của cảm biến theo NGSI-LD (profile iot) |
| Vận hành | Prometheus, Alertmanager, Grafana OSS | 3.15.0, 0.34.1, 13.2.3 | Apache-2.0, AGPL-3.0 | Giám sát cổng API và trạng thái từng thành phần, chỉ trong mạng nội bộ; cảnh báo tới chuông của quản trị đơn vị |
| Vận hành | Vector, Parseable | 0.59.0, 3.2.4 | MPL-2.0, AGPL-3.0 | Log tập trung đã che thông tin cá nhân, tùy chọn (profile logs) |
| Vận hành | Jaeger | 2.22.0 | Apache-2.0 | Truy vết phân tán qua APISIX, svc-files, svc-workflow, tùy chọn (profile trace) |
| Vận hành | restic | 0.19.1 | BSD-2-Clause | Sao lưu mã hóa CSDL, tệp, két |
Mọi giấy phép đều được OSI phê duyệt. Thành phần GPL, AGPL (ClamAV, PostGIS, Grafana, Parseable, DokuWiki) chạy thành
dịch vụ độc lập, giao tiếp qua mạng, không liên kết mã nên không xung đột với Apache-2.0. Giấy phép mọi gói, kể cả gói
gián tiếp, được kiểm tự động bằng make license-audit.
Cài đặt từ mã nguồn (Building From Source)
Yêu cầu hệ thống
| Thành phần | Phiên bản tối thiểu | Ghi chú |
|---|---|---|
| Docker Engine | 24.0 | kèm plugin docker compose v2 từ 2.17 và docker buildx |
| GNU Make | 4.0 | điều phối lệnh |
| Python | 3.10 | chỉ thư viện chuẩn, không cài thêm gì: dữ liệu mẫu, smoke, demo, sao lưu, cài đặt và các lệnh vận hành |
| RAM | 8 GB | profile mặc định (19 dịch vụ, 18 chạy liên tục) đo được khoảng 4,6 GiB khi chạy bản 1.3.0 (docker stats, 31/10/2026; ClamAV 0,9 GiB, lên 1,9 GiB trong khoảng 10 giây mỗi lần nạp lại chữ ký, Meilisearch 0,75 GiB, Keycloak 0,6 GiB, APISIX 0,5 GiB, Hasura 0,4 GiB). Từ #569 profile mặc định có 21 dịch vụ, 19 chạy liên tục: thêm rest (PostgREST, khoảng 25 MiB) và rest-init chạy một lần; bật profile studio thêm khoảng 300 MiB (đo trong CI ngày 04/11/2026, #568). Bật mô hình AI (profile ai, hai mô hình mặc định đã nạp) thêm khoảng 3,2 GiB, nên cần 16 GB |
| Đĩa trống | 10 GB | image khoảng 5 GB; mô hình AI thêm khoảng 2 GB |
Toàn bộ công cụ dùng để dựng Signet đều là phần mềm nguồn mở. Không cần bất kỳ công cụ nguồn đóng hay tự chế nào.
Các bước
# 1. Lấy mã nguồn
git clone https://github.com/HIT-Champion/Signet.git
cd Signet
# 2. Cấu hình (KHÔNG sửa mã nguồn để cấu hình — mọi tham số nằm trong .env)
make env # sinh .env từ .env.example, mật khẩu ngẫu nhiên; hoặc: cp .env.example .env rồi sửa
make check
# 3. Dựng image của đội và khởi động toàn bộ (lần đầu vài phút: tải image, ClamAV nạp chữ ký)
make up
# 4. Nạp dữ liệu mẫu: 2 đơn vị, phòng ban, 10 tài khoản, văn bản ở mọi bước của quy trình
make seed
Mở http://localhost:8080 và đăng nhập bằng một tài khoản ở mục Chạy thử. Dừng: make down (giữ dữ liệu)
· xóa sạch dữ liệu: make reset · xem mọi lệnh: make help. Lên máy chủ có tên miền và HTTPS (Caddy trước APISIX),
hoặc máy không có IP công khai như laptop, máy ở nhà (Cloudflare Tunnel, profile tunnel, không mở cổng nào):
docs/trien-khai.md.
Cài ra ngoài thư mục mã nguồn
make install dựng image của đội gắn thẻ phiên bản, chép docker-compose.yml, .env và các tệp cấu hình mà
container dùng sang PREFIX, rồi kiểm tra bản cài không còn trỏ về thư mục mã nguồn. Sau đó xóa thư mục mã nguồn đi
hệ thống vẫn chạy.
sudo install -d -o "$USER" /opt/moc # thư mục cài thuộc người vận hành, không cần chạy make bằng root
make install PREFIX=/opt/moc
make down # nếu đang chạy trong thư mục mã nguồn: hai bản dùng chung dữ liệu
cd /opt/moc && docker compose up -d --wait
python3 scripts/seed.py # dữ liệu mẫu, lần đầu
PREFIXmặc định là/opt/moc. Phiên bản lấy từgit describe; cài từ gói.tar.gzthì đặt tay:make install PREFIX=/opt/moc MOC_VERSION=0.1.0.- Gói có tệp
VERSIONở thư mục gốc thì phiên bản đã ghi sẵn trong đó (git archiveđiền khi đóng gói),make installtự đọc, không cần đặt tay. - Nâng cấp: dừng bản cài,
make installlại với cùngPREFIX. Compose, cấu hình và image được thay;.envcủa bản cài được giữ, trừMOC_VERSION,COMPOSE_PROFILESvàCOMPOSE_FILEdomake installđặt lại mỗi lần. Bản cài đang chạy có dữ liệu thì dùngscripts/nang_cap.sh nang /opt/moc: sao lưu trước, kiểm sau, có lệnh lùi (docs/trien-khai.mdmục Vận hành). - Gỡ:
make uninstall PREFIX=/opt/mocxóa đúng các tệp đã cài, giữ.envvà dữ liệu.
Chạy thử
Bản online https://signet.htechcs.com chạy bản phát hành mới nhất trên máy của đội, ra Internet qua Cloudflare
Tunnel; .github/workflows/ban-online.yml kiểm hằng ngày bản đó đúng thẻ mới nhất. Tài khoản dùng thử gửi kèm hồ sơ dự
thi; repo không công khai mật khẩu. Từ tối 31/10/2026, bản online chạy v1.4.0 cộng các bản vá đã gộp vào develop
nhưng chưa gắn thẻ: giao diện (#470, #481, #495, #500) và trợ lý hỏi đáp (#496, #503, #504); /api/status vẫn báo
1.4.0. Ứng dụng ngành Đổi, bù lịch giảng (#483) cài thêm bằng moc app install. Các tính năng chưa phát hành khác
(mục "Chưa phát hành" của CHANGELOG.md) có khi tự cài từ mã nguồn. Trợ lý hỏi đáp của bản online viết
câu trả lời qua API ngoài chuẩn OpenAI (MOC_ASK_API=openai, mô hình gpt-6-luna-wd, không phải mô hình nguồn mở): chỉ
câu hỏi và các đoạn căn cứ rời máy, đã che số CCCD/CMND, số điện thoại, email, số tài khoản; họ tên và địa chỉ không
được che. Bản tự cài mặc định dùng Ollama tại chỗ (DEPENDENCIES.md).
Bản tự cài: mật khẩu chung của các tài khoản mẫu là giá trị MOC_DEMO_PASSWORD trong .env. Văn thư, lãnh đạo,
tổ trưởng, trưởng bộ môn và quản trị đơn vị bắt buộc xác thực hai bước: sau mật khẩu nhập mã TOTP. make seed cài sẵn
cho các tài khoản này một khóa chung (MOC_DEMO_TOTP_SECRET); make totp in mã hiện tại và khóa để thêm một lần vào
ứng dụng xác thực trên điện thoại (FreeOTP, Aegis, Google Authenticator). Tài khoản thật thuộc các vai trò này tự cài
TOTP bằng mã QR ở lần đăng nhập đầu.
| Tài khoản | Vai trò | Thấy gì |
|---|---|---|
vanthu | Văn thư Trường CNTT & TT | Tiếp nhận, vào sổ; cấp số, phát hành văn bản đi; mọi văn bản của đơn vị |
truongkhoa | Hiệu trưởng (lãnh đạo đơn vị) | Hộp việc chỉ đạo, ký duyệt văn bản đi; dashboard điều hành; mọi văn bản của đơn vị |
totruongdt, truongbmktpm | Tổ trưởng Đào tạo, trưởng Bộ môn KTPM | Văn bản giao cho tổ, bộ môn; phân công; duyệt dự thảo |
chuyenviendt, giamkhao, giangvienktpm | Chuyên viên, giảng viên | Văn bản được giao cho mình; soạn, trình văn bản đi |
quantri | Quản trị đơn vị | Sổ kiểm toán của đơn vị; không đọc nội dung văn bản |
vanthukt, truongkhoakt | Trường Kinh tế | Chỉ văn bản của Trường Kinh tế |
Ban giám khảo thử nhanh bằng giamkhao (chuyên viên, không cần TOTP): hộp việc có sẵn một công văn khẩn chờ xử lý
và một dự thảo phúc đáp bị tổ trưởng trả lại chờ sửa.
| Địa chỉ trên bản tự cài | Là gì | Đăng nhập |
|---|---|---|
| http://localhost:8080 | Văn phòng điện tử | Có |
| http://localhost:8080/ca-nhan/ | Không gian cá nhân P.A.R.A | Có |
| http://localhost:8080/tai-lieu-api/ | Tài liệu API (Swagger UI): đọc API lõi và API Văn phòng điện tử, đăng nhập để gọi thử qua cổng | Không bắt buộc |
| http://localhost:8080/bang-tin/ | Bảng tin đơn vị, sau khi cắm bằng make app-install APP=apps/bang-tin/app.yaml | Có |
| http://localhost:8080/sinh/ | Ứng dụng sinh từ bảng: danh sách, biểu mẫu dựng từ bảng tạo trong Studio, sau khi cắm bằng make app-install APP=apps/sinh/app.yaml | Có |
| http://localhost:8080/xac-thuc | Cổng xác thực văn bản: nhập mã hoặc thả tệp PDF; mã của văn bản mẫu ở trang chi tiết văn bản (Văn bản đi, tab Đã phát hành) | Không |
| http://localhost:8080/trang-thai | Trạng thái hệ thống | Không |
| http://127.0.0.1:8180/admin | Quản trị Keycloak, chỉ mở trên máy chủ (tài khoản KEYCLOAK_ADMIN_*) | Có |
| http://127.0.0.1:3300 | Grafana giám sát cổng API, chỉ mở trên máy chủ (từ xa: đường hầm SSH) | Không |
| http://127.0.0.1:3400 | Supabase Studio: người vận hành nền tảng tạo bảng cho ứng dụng sinh, profile studio, chỉ mở trên máy chủ (từ xa: đường hầm SSH) | Không |
Vận hành và kiểm thử
Các việc của người quản trị trên bản cài đang chạy nằm ở docs/van-hanh.md:
| Việc | Lệnh chính |
|---|---|
| Thêm đơn vị (khoa, phòng, trường thành viên) | python3 scripts/moc.py tenant create … |
| Sao lưu và khôi phục mọi CSDL, tệp, két vào kho restic mã hóa | make backup, make restore |
| Két bí mật OpenBao: giới hạn, nâng cấp két cũ để ký số | make demo-ket-bi-mat |
GitOps và tự phục hồi: systemd timer hoặc cron, mỗi phút một lượt; theo nhánh deploy hoặc theo thẻ phát hành (MOC_GITOPS_FOLLOW=release), nâng có sao lưu và tự lùi (MOC_GITOPS_MODE=nang-cap); đặt MOC_GITOPS_ALLOWED_SIGNERS thì chỉ áp bản đã ký | make reconcile |
| Giám sát cổng API bằng Prometheus + Grafana | đường hầm SSH tới cổng 3300 |
Ứng dụng sinh từ bảng: tạo bảng trong Supabase Studio, PostgREST sinh API, trang /sinh dựng biểu mẫu | thêm studio vào MOC_EXTRA_PROFILES, make up |
Log tập trung: Vector + Parseable, tra theo mã yêu cầu X-Request-Id | make logs-up, make logs-tra ID=… |
| Hội tụ IT/OT: broker NGSI-LD, cảm biến | make demo-it-ot |
| Dữ liệu công khai: bản chụp thông tư Bộ GD&ĐT từ Công báo, kiểm SHA-256, tuổi dữ liệu | make du-lieu-mo |
| Cắm ứng dụng bằng manifest, không sửa lõi; gỡ giữ dữ liệu | python3 scripts/moc.py app install …, app list, app remove |
Tường lửa ứng dụng web: chặn, chỉ ghi nhật ký hay tắt; đọc dòng chặn theo X-Request-Id | MOC_WAF=On · DetectionOnly · Off |
| Kiểm sổ kiểm toán ngoài CSDL | make audit |
| Lệnh | Kiểm gì | Cần |
|---|---|---|
make test | Test đơn vị của svc-files, svc-workflow, lệnh vận hành; test của Văn phòng điện tử, gồm kiểm form theo schemas/ trên cùng bộ ca thử với máy chủ và CSDL; test của Không gian cá nhân, Bảng tin, Đơn nghỉ phép, ứng dụng Đổi, bù lịch giảng và trang Tài liệu API | Python + uv; Node 24 và npm ci trong apps/office |
make smoke | Đi trọn luồng văn bản đến, văn bản đi qua cổng APISIX; cổng xác thực, thông báo WebSocket, sổ kiểm toán; chặn dữ liệu sai, EICAR, đường quản trị; cách ly đơn vị; giới hạn tốc độ; két bí mật; reconciler; nộp lưu; giám sát; WAF chặn tải tấn công mà không chặn nhầm dữ liệu thật | Hệ thống đang chạy + make seed |
make e2e | Trình duyệt thật (Playwright, trong container): form sai bị chặn trước khi gửi, thả tệp vào trang xác thực, hai người dùng cùng lúc nhận thông báo, sổ kiểm toán, dashboard, ký số | Như trên |
make do-doc-van-ban, do-hoi-dap, do-giao-viec, do-che-pii, do-so-lieu-sau | Đo các tác tử AI trên bộ mẫu có đáp án (đúng / sai / trống từng trường, recall@3, độ phủ); số đo "sau" theo đặc tả §8 | Hệ thống đang chạy (do-che-pii không cần) |
db/tests/ | Schema, quyền theo vai trò và đơn vị, ràng buộc, sổ kiểm toán (kể cả các kiểu sửa lén) trên PostgreSQL + Hasura thật | xem db/README.md |
make sbom, make license-audit | SBOM CycloneDX của cây mã nguồn (Syft); giấy phép của mọi gói npm, Python, action CI, kể cả gói gián tiếp, theo chính sách trong DEPENDENCIES.md | Docker, mạng tới PyPI |
CI chạy cả bảng trên và các màn demo cho mọi pull request đổi mã: dựng từ mã nguồn bằng
đúng các lệnh cài đặt, diễn tập sao lưu và khôi phục, cài ra thư mục khác, GitOps, quét bí mật và lỗ hổng phụ thuộc.
Nhắc hạn chỉ kiểm được khi hạn ngắn: MOC_SLA_DURATION=PT20S make up rồi MOC_SLA_DURATION=PT20S make smoke.
Xử lý sự cố
| Hiện tượng | Nguyên nhân và cách xử lý |
|---|---|
make check báo thiếu .env hoặc docker compose | Chạy make env để sinh .env; cài plugin Docker Compose v2 từ 2.17 trở lên |
make up dừng khi kéo hay dựng image: hết thời gian chờ tới docker.io, hoặc toomanyrequests | Mạng chặn Docker Hub hoặc đã hết lượt tải ẩn danh. Cho Docker kéo qua bản sao mirror.gcr.io (khóa registry-mirrors, cần sudo) theo mục 2b của docs/trien-khai.md |
make up chạy lâu, dịch vụ còn starting hoặc unhealthy | Lần đầu phải tải khoảng 5 GB image và ClamAV nạp chữ ký virus, mất vài phút; make up chờ tối đa 10 phút. Theo dõi bằng make ps, make logs |
| Cổng 8080 đã có chương trình khác dùng | Đặt MOC_HTTP_PORT=8081 và MOC_PUBLIC_URL=http://localhost:8081 trong .env trước lần make up đầu tiên: realm Keycloak chỉ nạp địa chỉ này một lần, đã chạy rồi thì make reset rồi dựng lại |
| Mở bằng IP trong mạng LAN thì không đăng nhập được | Trình duyệt chỉ cho dùng Web Crypto (đăng nhập PKCE, tính SHA-256 ở trang xác thực) trên https hoặc localhost. Dùng localhost, hoặc lên HTTPS theo docs/trien-khai.md |
| Mã TOTP bị từ chối | Đồng hồ điện thoại lệch (mã đổi mỗi 30 giây): bật giờ tự động, hoặc lấy mã theo đồng hồ máy chủ bằng make totp. Sai 10 lần thì Keycloak tạm khóa tài khoản |
| Báo "Cổng an ninh chặn nội dung này vì có chữ giống mẫu tấn công" (HTTP 403) | WAF ở cổng APISIX thấy chữ giống tải tấn công. Sửa chữ hoặc tên tệp rồi gửi lại. Nếu là dữ liệu thật bị chặn nhầm thì lấy mã yêu cầu (X-Request-Id) của lần chặn, tìm bằng docker compose logs apisix | grep <mã> và thêm loại trừ theo platform/apisix/README.md; tạm thời có thể đặt MOC_WAF=DetectionOnly (chỉ ghi nhật ký) rồi docker compose up -d apisix |
| Máy chậm hoặc hết RAM sau khi bật AI | Mô hình cần thêm tới 6 GB RAM. Tắt bằng docker compose --profile ai stop ollama; các tác tử tự về chế độ không cần mô hình |
Chưa gỡ được thì mở issue theo mẫu báo lỗi,
kèm kết quả make ps và đoạn make logs của dịch vụ lỗi.
Tài liệu
Cấu trúc thư mục
Mã đội tự viết nằm ở apps/, services/ và db/. platform/ chỉ chứa cấu hình cho các phần mềm nguồn mở mà lõi dùng
nguyên bản (image chính thức, không sửa mã thượng nguồn).
apps/ Văn phòng điện tử (office/, Nuxt 4) · Không gian cá nhân P.A.R.A (ca-nhan/) · Bảng tin đơn vị
(bang-tin/), Đơn nghỉ phép (nghi-phep/), Đổi, bù lịch giảng (lich-giang/): ba ứng dụng cắm bằng
moc app install · Tài liệu API bằng Swagger UI (tai-lieu-api/)
services/ svc-workflow/: Hasura Actions, quy trình BPMN, thông báo, nhắc hạn, gợi ý giao việc
svc-files/: tệp, kiểm dịch, tìm kiếm, dựng PDF, ký số, cổng xác thực, các tác tử AI
ot-sensor/: cảm biến nhiệt độ giả lập (profile iot-sim)
db/ Lược đồ PostgreSQL, quyền Hasura theo vai trò và đơn vị, sổ kiểm toán chuỗi băm; tests/
schemas/ JSON Schema của form, dùng chung cho giao diện, dịch vụ và CSDL
platform/ Cấu hình Keycloak, APISIX, Centrifugo, OpenBao, giám sát, log tập trung, systemd
scripts/ Lệnh vận hành (moc.py, seed, smoke, backup, audit, reconcile, demo), cài đặt, công cụ của repo
(kiểm PR, phát hành, header giấy phép, sinh sơ đồ kiến trúc so_do_kien_truc.py)
seed/ tests/e2e/ Dữ liệu mẫu hư cấu · test trình duyệt (Playwright)
docs/ Tài liệu sản phẩm; api/: tài liệu API; du-thi/: tài liệu dự thi
docker-compose.yml Toàn hệ thống, chia profile core, app, ai, iot, logs…
Makefile Lối vào mọi lệnh: make env, up, seed, test, smoke, install…
Signet trước đây tên Mộc. Tên mã kỹ thuật
mocvẫn giữ trong mã và cấu hình: biếnMOC_*, realmmoc, lệnhscripts/moc.py, imagemoc/*, thư mục cài/opt/moc.
Đóng góp và liên hệ
- Báo lỗi, đề xuất tính năng: mở issue theo mẫu báo lỗi hoặc mẫu đề xuất; xem mọi issue.
- Lịch sử thay đổi:
CHANGELOG.mdtheo Keep a Changelog; các bản phát hành ở Releases. - Đóng góp mã nguồn: đọc
CONTRIBUTING.mdvà quy trình Gitdocs/git_flow.mdtrước khi mở pull request; tuân theoCODE_OF_CONDUCT.md. - Lỗ hổng bảo mật: không mở issue công khai — báo riêng tư theo
SECURITY.md.
| Thành viên | GitHub | |
|---|---|---|
| Nguyễn Huy Hoàng | HoangTechCS-AIE | nguyenhuyhoangqbx5@gmail.com |
| Đinh Văn Vượng | Vanvuong2005827 | vanvuong2005827@gmail.com |
| Nguyễn Lê Hoài Nam | nguyenlehoainam | namngyenhoai21@gmail.com |
Giấy phép
Phát hành theo Apache License 2.0 — một giấy phép được OSI phê duyệt. Toàn văn: LICENSE. Mục đích
lựa chọn giấy phép: NOTICE.
Mọi tệp đều có thông tin bản quyền và giấy phép theo chuẩn REUSE: tệp mã mang header
Apache-2.0 (make license-check), tệp không chèn được header (JSON, ảnh, PDF, tài liệu) khai trong
REUSE.toml. Kiểm toàn bộ kho: uvx --from reuse==5.0.2 reuse lint.
Signet điều phối các phần mềm nguồn mở thượng nguồn ở dạng nguyên bản, không sao chép và không chỉnh sửa mã nguồn
của chúng vào kho này. Logo các dự án trong sơ đồ kiến trúc là nhãn hiệu của chủ sở hữu, chỉ dùng để nhận diện thành
phần, không thuộc giấy phép Apache-2.0 của Signet: docs/anh/logo/NGUON.md.