Evidence: báo cáo dữ liệu viết bằng SQL và markdown, nhìn từ một startup SaaS B2B
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
Evidence là gì, sau khi dự án đã đổi hướng, và có nên thử không?
Evidence tự giới thiệu là công cụ "sẵn sàng cho agent" để tạo báo cáo từ dữ liệu của bạn; README mô tả nó là lựa chọn mã nguồn mở, dựa trên mã, thay cho các công cụ business intelligence kéo thả, nơi báo cáo được viết bằng SQL và markdown. [1] Người dùng có thể phát triển bằng agent của Evidence hoặc trên máy cá nhân với Claude Code hay Cursor, rồi tự lưu trữ hoặc xuất bản trên nền tảng Evidence Studio. [1]
Điều cần hiểu trước khi đọc tiếp là dự án đã đổi hình dạng. Tài liệu di chuyển gọi phiên bản cũ là "legacy Evidence", một bộ sinh trang web tĩnh dùng markdown và DuckDB SQL; bản hiện tại chạy SQL ở phía máy chủ và thêm nhiều tính năng nằm trên nền tảng Studio. [10] Kho GitHub hiện cũng chỉ là bản sao chỉ-đọc của một kho nội bộ. [11]
Khuyến nghị: một startup có đội dữ liệu nhỏ, đã có kho dữ liệu và thích viết SQL có thể thử Evidence cho báo cáo nội bộ. Nếu cần phân quyền theo từng người xem hoặc bảng điều khiển nhúng cho khách hàng, các tài liệu cho thấy phần tự lưu trữ không đáp ứng, và đó là tính năng của nền tảng thương mại. [4][9]
Vì sao nhiều đội muốn chuyển báo cáo sang dạng mã
Công cụ BI kéo thả thuận tiện lúc đầu nhưng báo cáo khó kiểm soát phiên bản, khó rà soát và khó nhân bản khi số lượng tăng. Mô hình của Evidence đặt cược rằng nếu báo cáo là tệp văn bản gồm SQL và markdown thì có thể dùng Git, pull request và rà soát mã như với phần mềm. [1]
Tài liệu CLI vận hành theo đúng tinh thần này: dự án nằm trong kho GitHub, sửa cục bộ bằng evidence dev, mở pull request để nhận liên kết xem trước, và hợp nhất để phát hành thay đổi. [7] Báo cáo là mã cũng giúp agent lập trình đọc và sửa được. [1]
Cái giá là ngưỡng kỹ năng: người viết báo cáo phải biết SQL và quen với quy trình phát triển. Với nhóm kinh doanh không biết SQL, cách này chuyển việc làm báo cáo về cho đội dữ liệu, trừ khi họ dùng trình soạn thảo web hoặc agent trên Studio. [3][4]
Hai lớp: lõi mã nguồn mở và nền tảng Studio xung quanh nó
Phần có thể nhìn thấy trong kho là lõi hiển thị báo cáo cùng giao diện dòng lệnh (CLI). CLI gồm máy chủ phát triển để xem trước báo cáo khi viết, lệnh chạy truy vấn, xem siêu dữ liệu và kiểm tra mã. [7] Trên bản này, tài liệu di chuyển nói cú pháp thành phần dùng Markdoc, SQL chạy trên máy chủ chứ không trong trình duyệt, và cấu hình được diễn đạt bằng khai báo thay vì thực thi JavaScript tùy ý. [10]
Quanh lõi là nền tảng Evidence Studio: kho dữ liệu được quản lý (Evidence Warehouse), mô hình SQL, đăng nhập một lần, kiểm soát truy cập, bảo mật mức hàng, agent cho người phát triển và người xem, trình soạn thảo web cộng tác, phân tích nhúng và máy chủ MCP. Bảng so sánh trong tài liệu tự lưu trữ đánh dấu tất cả những mục này là không có trong bản tự lưu trữ. [4]
Kết nối dữ liệu có hai kiểu. Nếu dùng Evidence Warehouse, chỉ cần evidence login. Nếu dùng kết nối trực tiếp tới kho của riêng mình, thêm tệp connection.yaml vào gốc dự án và CLI sẽ truy vấn kho trực tiếp từ máy người dùng mà không cần đăng nhập. [8] Tài liệu minh họa cho Snowflake và BigQuery. [8]
Từ tệp markdown đến trang báo cáo: ai chạy truy vấn, bằng danh tính nào
Với bản tự lưu trữ, luồng gần như thẳng: người xem mở trang, máy chủ evidence serve chạy các truy vấn trong báo cáo trên kho dữ liệu qua connection.yaml, rồi trả về trang đã hiển thị. Tài liệu migration nói bản mới không cần bước build và truy vấn chạy lại khi tải trang, khác bản cũ; vì evidence serve được mô tả là giống evidence dev nhưng làm cứng, có thể giả định cách chạy tương tự, và điều này cần kiểm chứng. [4][10]
Điểm cần lưu ý là danh tính truy vấn. Tài liệu xác thực viết rõ rằng mọi người dùng đã xác thực đều thấy cùng các báo cáo, được truy vấn bằng một danh tính kho dữ liệu duy nhất khai báo trong connection.yaml. Evidence tự lưu trữ không đọc danh tính người dùng từ proxy, nên không thể lọc dữ liệu theo từng người xem. [9]
Hệ quả thiết kế: tài khoản kho dữ liệu dùng cho Evidence nên là tài khoản chỉ đọc, giới hạn trong các bảng hoặc view đã chuẩn bị cho báo cáo. Tài liệu kết nối cũng cảnh báo connection.yaml chứa thông tin xác thực, nên không được commit và phải kiểm soát cả tệp khóa được tham chiếu. [8] Khi triển khai bằng Docker, bí mật được chuyển sang biến môi trường dạng ${VAR}. [4]
Những gì tài liệu xác nhận ở bản tự lưu trữ
README liệt kê ba khả năng chính: tạo báo cáo bằng SQL và markdown, phát triển bằng agent hoặc cục bộ, và tự lưu trữ hoặc xuất bản trên Studio. Cài đặt qua một dòng lệnh tải từ evidence.studio, sau đó evidence init tạo dự án và evidence dev chạy máy chủ xem trước. [1] Nên rà soát script cài đặt trước khi chạy ở môi trường sản xuất.
Với tự lưu trữ, tài liệu cho biết có ảnh Docker chính thức evidencedev/serve chạy evidence serve, tương tự evidence dev nhưng được làm cứng như máy chủ sản xuất. Các nền tảng đã thử gồm Vercel, Render, Fly.io và Railway. Bảo vệ truy cập bằng HTTP Basic Auth, hoặc tắt xác thực khi chạy trong mạng riêng tin cậy, hoặc đặt sau proxy xác thực. [4][9]
Tài liệu di chuyển cho biết CLI có lệnh evidence docs để tra cứu cú pháp thành phần, hữu ích cho agent. Cây tệp liệt kê rất nhiều thành phần biểu đồ và nguồn dữ liệu, nhưng nghiên cứu này không đọc chi tiết từng mục. [10]
Cần phân biệt rõ khả năng tự lưu trữ với khả năng của Studio như đã nêu. Các phát biểu về quy mô như "hàng trăm triệu hàng" trong tài liệu di chuyển là khẳng định của nhà cung cấp cho Studio, chưa được kiểm chứng ở đây. [10]
Từ Evidence cũ sang Evidence mới: điều gì đã thay đổi và ai bị ảnh hưởng
Tài liệu di chuyển so sánh hai thế hệ. Bản cũ là bộ sinh trang tĩnh: cú pháp Svelte, SQL DuckDB chạy trong trình duyệt bằng WebAssembly, dữ liệu chuẩn bị ở bước build, và người dùng tự cấu hình lưu trữ. Bản mới dùng Markdoc, SQL gốc của kho dữ liệu chạy phía máy chủ, truy vấn chạy lại khi tải trang. [10]
Một số tính năng cũ không có thay thế trực tiếp: trang theo mẫu có tham số, truy vấn nguồn trong thư mục sources, tệp Svelte và thành phần Svelte tùy biến, biểu thức JavaScript trong trang, biểu đồ hộp, biểu đồ Venn và liên kết đi sâu trên bản đồ. Công cụ evidence migrate chuyển phần cơ học và cảnh báo phần còn lại. [10]
Người đã dùng Evidence cũ không nên giả định dự án cũ chạy nguyên vẹn; người mới nên cảnh giác với hướng dẫn cũ trên mạng.
Một chi tiết cần kiểm chứng: API GitHub trả về bản phát hành mới nhất là @evidence-dev/evidence@40.1.8 ngày 6/2/2026, trong khi tài liệu CLI nhắc phiên bản như 0.9.x. [7] Nghiên cứu này không xác định được hai dãy phiên bản liên hệ với nhau ra sao.
Đội nào nên cân nhắc, đội nào nên bỏ qua
Phù hợp nhất là đội dữ liệu hoặc kỹ thuật nhỏ trong startup, đã có kho dữ liệu hoặc cơ sở dữ liệu phân tích và quen Git. Họ được lợi từ việc báo cáo là mã, có xem trước qua pull request và có thể nhờ agent hỗ trợ. [1][7]
Nhóm thứ hai là đội muốn dữ liệu không rời khỏi hạ tầng của mình. Tài liệu tự lưu trữ nêu đây là một lý do hợp lý, cùng lý do thứ hai là dự án sở thích không muốn trả phí dịch vụ. [4] Nhóm thứ ba là đội đang dùng Evidence cũ và cần đánh giá việc chuyển đổi. [10]
Không phù hợp khi bộ phận kinh doanh cần tự khám phá dữ liệu mà không biết SQL, khi cần phân quyền theo người hoặc theo hàng dữ liệu, hoặc khi cần báo cáo nhúng cho khách hàng bên ngoài. Tài liệu xác thực khuyên các triển khai cần truy cập phân biệt nên dùng Studio. [9]
Tình huống đề xuất: báo cáo sức khỏe khách hàng cho một startup SaaS B2B quản lý nhân sự
Đây là tình huống giả định. Một startup SaaS B2B tại Hà Nội bán phần mềm chấm công và tính lương cho khoảng bốn mươi doanh nghiệp vừa và nhỏ. Dữ liệu sử dụng sản phẩm nằm trong một cơ sở dữ liệu phân tích, doanh thu nằm ở hệ thống thanh toán, và người làm báo cáo là một kỹ sư dữ liệu kiêm hỗ trợ. Hằng tuần, nhóm thành công khách hàng và ban sáng lập cần một báo cáo chung về mức sử dụng, tỷ lệ rời bỏ và các tài khoản có nguy cơ.
Đề xuất: dùng Evidence tự lưu trữ cho báo cáo nội bộ. Kỹ sư viết vài trang SQL cộng markdown trên một số view chỉ đọc đã chuẩn hóa, chạy bằng evidence dev, rà soát qua pull request, rồi triển khai ảnh Docker tới một dịch vụ như Render hoặc Fly.io, đặt sau Basic Auth hoặc một proxy đăng nhập của công ty. [4][5][6][9] Chỉ số rời bỏ được định nghĩa một lần trong SQL của view và tái sử dụng ở mọi trang, là lợi ích chính của cách làm dạng mã.
Ranh giới cần giữ: báo cáo này chỉ cho nhân sự nội bộ, vì mọi người xem thấy cùng dữ liệu. Nếu startup về sau muốn gửi cho từng khách hàng một trang sử dụng của riêng họ, đó chính là phân tích nhúng và bảo mật mức hàng của Studio, không có ở bản tự lưu trữ. [4][9] Không đưa dữ liệu cá nhân của người lao động, như lương từng người, vào báo cáo nội bộ; chỉ dùng số liệu tổng hợp.
Chỉ số đề xuất theo dõi trong thử nghiệm: thời gian từ yêu cầu báo cáo mới đến lúc có bản xem được, số lần định nghĩa chỉ số bị lệch giữa các báo cáo, và số giờ bảo trì mỗi tháng. Ngưỡng cụ thể do đội tự đặt. Nếu muốn lưu hồ sơ phương pháp, phamvanthu.com có thể là nơi tham chiếu.
Dựng ảnh Docker, đặt biến môi trường và theo dõi bộ nhớ
Bước chung cho mọi nền tảng theo tài liệu: thêm Dockerfile dựa trên evidencedev/serve, chuyển bí mật khỏi connection.yaml sang biến ${VAR}, commit connection.yaml (mặc định bị gitignore), rồi đặt biến môi trường gồm EVIDENCE_BASIC_USER, EVIDENCE_BASIC_PASSWORD và các biến tham chiếu. Cổng mặc định là 3000. [4]
Các hướng dẫn nền tảng có chi tiết thực tế. Với Fly.io, máy 256 MB mặc định quá nhỏ và máy chủ bị hệ điều hành kết thúc vì thiếu bộ nhớ khi khởi động; tài liệu yêu cầu tối thiểu 512 MB và lưu ý Fly không cấp biến PORT nên cổng nội bộ phải là 3000. [5] Với Render, gói miễn phí tạm dừng dịch vụ khi nhàn rỗi, nên khởi động lại sẽ chậm. [6]
Tài liệu tự lưu trữ nói thẳng rằng không có phí nền tảng nhưng có chi phí hạ tầng và bảo trì, và người triển khai tự lo bảo mật, giám sát và mở rộng. [4] Telemetry ẩn danh có thể tắt bằng EVIDENCE_TELEMETRY_DISABLED. [4][7] Nâng cấp CLI dùng evidence upgrade, và CLI có thể yêu cầu nâng cấp nếu phiên bản thấp hơn mức tối thiểu được hỗ trợ. [7]
Xác thực chung, một danh tính kho dữ liệu và telemetry cần biết
Xác thực tích hợp của bản tự lưu trữ chỉ là HTTP Basic Auth dùng chung hoặc tắt xác thực trong mạng riêng như VPN hay Tailscale. Trình duyệt giữ thông tin trong bộ nhớ đến khi thoát, không có nút đăng xuất, và muốn buộc mọi người xác thực lại phải đổi mật khẩu rồi triển khai lại. [4]
Để dùng danh tính công ty, tài liệu hướng dẫn đặt evidence serve sau proxy xác thực qua OIDC hoặc SAML, như Cloudflare Access, oauth2-proxy hay Pomerium, và đặt Evidence trong mạng riêng để proxy là cổng vào duy nhất. [9] Nhưng xác thực chỉ kiểm soát ai vào được, không giới hạn dữ liệu mỗi người thấy. [9]
Về quyền riêng tư, CLI gửi telemetry ẩn danh: một sự kiện cho mỗi lệnh, và với evidence serve có thêm nhịp tim mỗi 24 giờ cùng mã dự án ngẫu nhiên; tài liệu nói không gửi dữ liệu, truy vấn, đường dẫn tệp hay thông tin kho mã, nhưng yêu cầu mang địa chỉ IP dùng để định vị cấp quốc gia. Có thể tắt bằng biến môi trường hoặc lệnh evidence telemetry disable. [7] Tổ chức nghiêm ngặt nên tắt và kiểm tra lưu lượng ra ngoài.
MIT cho kho này, còn Evidence Studio là sản phẩm riêng
LICENSE gốc là MIT, bản quyền 2026 Evidence, cho phép dùng, sao chép, sửa, hợp nhất, xuất bản, phân phối, cấp phép lại và bán với điều kiện giữ thông báo bản quyền và miễn trừ bảo hành. README cũng khẳng định MIT. [1][2] Cây tệp còn có các tệp giấy phép riêng của phông chữ đi kèm CLI, chưa được đọc ở đây.
Phạm vi quan trọng: MIT chỉ áp dụng cho mã trong kho này. Evidence Studio, Evidence Warehouse, agent, máy chủ MCP và các tính năng được tài liệu đánh dấu là chỉ có trên Studio là dịch vụ do nhà cung cấp vận hành; nghiên cứu này không thấy điều khoản sử dụng của chúng nên không kết luận gì về chúng. [4] Giấy phép cũng không bao phủ dữ liệu của bạn, thư viện phụ thuộc, phông chữ và thành phần bên thứ ba giữ giấy phép riêng, hay nhãn hiệu Evidence.
Về đóng góp, CONTRIBUTING nói kho này là bản chiếu chỉ-đọc của kho rộng hơn: pull request được rà soát ở đây, nhưng việc hợp nhất xảy ra ở kho nội bộ và PR gốc bị đóng thay vì hợp nhất. [11] Không thấy chỉ dẫn về CLA trong tệp đó. Điều này nghĩa là người dùng có thể fork theo MIT nhưng phần quyết định lộ trình nằm ở nhà cung cấp.
Chi phí: miễn phí giấy phép, trả bằng hạ tầng, kỹ năng SQL và rủi ro phụ thuộc
Bản tự lưu trữ không có phí nền tảng theo tài liệu; chi phí gồm hạ tầng chạy container, kho dữ liệu hoặc tài nguyên truy vấn mà báo cáo gọi, và công bảo trì. [4] Không có bảng giá nào trong nguồn đã đọc và bài này không suy đoán giá của Studio.
Chi phí kho dữ liệu dễ bị đánh giá thấp vì truy vấn chạy lại khi tải trang. [10] Nếu báo cáo gọi truy vấn nặng trên kho tính phí theo lượng quét, nhiều người xem có thể làm tăng hóa đơn. Cách giảm là dùng view tổng hợp và theo dõi mức dùng kho khi thử.
Nhân lực: một kỹ sư dữ liệu biết SQL và Git, vài giờ mỗi tuần cho đến khi quy trình ổn định, cộng thời gian của người duyệt định nghĩa chỉ số. Nếu sau này cần tính năng của Studio, chi phí chuyển sang mô hình thuê bao với điều khoản nhà cung cấp quyết định. [4]
So sánh theo cách tiếp cận: BI dạng mã, BI kéo thả và bảng tính
BI kéo thả như Power BI, Tableau hay Looker Studio cho phép người không viết mã tự dựng và khám phá, đổi lại là kiểm soát phiên bản và rà soát yếu hơn. Evidence nằm ở phía ngược lại: báo cáo là tệp, cần SQL, nhưng dễ rà soát. [1] Với đội kinh doanh tự phục vụ, bảng kéo thả thường tự nhiên hơn.
Các công cụ khác như Metabase, Apache Superset hay Observable Framework cũng nằm trong vùng giữa giao diện và mã; bài này không so sánh chi tiết vì tài liệu của họ không nằm trong nguồn đã đọc.
Bảng tính hoặc script Python gửi báo cáo định kỳ là phương án đơn giản nhất cho một vài báo cáo; khi số báo cáo tăng và định nghĩa chỉ số cần chung, cách làm dạng mã bắt đầu có lợi. Tự lưu Evidence đổi lấy kiểm soát dữ liệu bằng việc bỏ phân quyền theo người, trong khi Studio đổi ngược lại. [4] Quyết định nên dựa trên việc báo cáo của bạn cần ai xem và xem những gì.
Những điều kiện nên dừng lại
Thứ nhất, phân quyền: bản tự lưu trữ không có tài khoản người dùng, đăng nhập một lần hay bảo mật mức hàng, và mọi người xem thấy cùng dữ liệu. [4][9] Thứ hai, sự ổn định của hướng đi: dự án đã chuyển từ bộ sinh trang tĩnh sang kiến trúc khác, nhiều tính năng cũ không có thay thế, nên rủi ro thay đổi tiếp là có thật. [10]
Thứ ba, sự phụ thuộc: kho là bản chiếu chỉ-đọc, lộ trình do nhà cung cấp quyết định, và CLI phát triển liên kết với Studio qua đăng nhập, xem trước PR và telemetry. [7][11] Thứ tư, bản tự lưu trữ yêu cầu kết nối trực tiếp, nghĩa là không dùng được Evidence Warehouse hay mô hình SQL của Studio. [4]
Thứ năm, nghiên cứu này không đo hiệu năng, không chạy thử, không đọc tài liệu từng thành phần biểu đồ hay từng nguồn dữ liệu, và không xem điều khoản của Studio.
Thử nghiệm bốn tuần với ba báo cáo nội bộ
Tuần 1: chọn ba báo cáo hiện có trong bảng tính hoặc công cụ khác, chốt định nghĩa chỉ số với người chịu trách nhiệm, tạo tài khoản kho dữ liệu chỉ đọc và các view tổng hợp. Dựng dự án bằng evidence init và kết nối trực tiếp qua connection.yaml. [8] Tiêu chí hoàn thành: ba truy vấn chính cho kết quả khớp bản hiện có trong ngưỡng sai khác đã thống nhất.
Tuần 2: viết ba trang, mở pull request cho từng trang và đo thời gian rà soát. Chạy evidence validate để bắt lỗi cú pháp và SQL. [10] Tuần 3: đóng gói bằng ảnh Docker, triển khai lên một nền tảng đã được tài liệu hướng dẫn, đặt Basic Auth hoặc proxy, kiểm tra bộ nhớ và độ ổn định khi khởi động. [4][5][6]
Tuần 4: đánh giá. Ghi nhận thời gian tạo báo cáo mới, số lần lệch định nghĩa chỉ số, mức dùng kho dữ liệu, giờ bảo trì, và phản hồi của người xem. Tiêu chí đạt gợi ý: người xem lấy được thông tin cần mà không cần hỏi lại đội dữ liệu cho phần lớn câu hỏi, và công bảo trì nằm trong mức đã thống nhất.
Tiêu chí dừng: cần phân quyền theo người xem, truy vấn làm tăng chi phí kho vượt ngân sách, hoặc phụ thuộc vào Studio trở thành điều kiện bắt buộc. Mọi ngưỡng số do đội đặt trước khi bắt đầu.
Điều rút ra
Evidence đáng thử như một cách làm báo cáo nội bộ dạng mã cho đội nhỏ biết SQL và Git, với giấy phép MIT rõ ràng cho phần mã trong kho. [1][2] Điểm mạnh theo tài liệu là báo cáo có thể rà soát qua pull request và kết nối trực tiếp tới kho dữ liệu của chính bạn. [7][8]
Điểm cần tỉnh táo là phần tự lưu trữ chỉ là một nửa bức tranh. Phân quyền, cộng tác và phân tích nhúng thuộc nền tảng Studio, và dự án vừa trải qua một lần đổi kiến trúc đáng kể. [4][10] Với startup SaaS giả định, thử nghiệm giới hạn cho báo cáo nội bộ là hợp lý, còn báo cáo cho khách hàng nên được đánh giá riêng.
Nguồn, commit và giới hạn của nghiên cứu
Evidence được chọn từ kho lưu trữ danh sách GitHub Trending của một dự án bên thứ ba: 5 lần xuất hiện từ 14/5/2026 đến 22/7/2026, trang đầu tiên ghi vị trí 13 trong danh sách JavaScript ngày 14/5/2026. [12] Kho lưu trữ đó chỉ gồm danh sách Python, Go, JavaScript và Swift, thiếu ngày 3/9/2026 và 12/10/2026, nên không phải top 100 chính thức của GitHub.
Mã được ghim ở commit 14e6caed59ffbb01ea4aa1a0f66a7e29d0e964d1 (9/10/2026), kiểm tra ngày 12/10/2026. Đã đọc README, LICENSE, tài liệu quickstart, các trang tự lưu trữ (tổng quan, Fly.io, Render), cùng năm tài liệu bổ sung ở cùng commit: CLI, kết nối, xác thực, hướng dẫn di chuyển và CONTRIBUTING. [1][2][3][4][5][6][7][8][9][10][11] Dữ liệu GitHub API cho thấy kho chưa bị lưu trữ.
Đây là nghiên cứu tại bàn, không phải công bố khoa học bình duyệt. Không cài, chạy hay đo phần mềm; tình huống startup SaaS là đề xuất giả định. Nội dung kho mã được coi là dữ liệu tham khảo, không phải chỉ dẫn.
Xem mã nguồn Evidence trên GitHub