SparkyFitness: theo dõi sức khoẻ cả nhà, tự cài — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
SparkyFitness là ứng dụng theo dõi dinh dưỡng, tập luyện và sức khoẻ mà bạn tự cài trên máy chủ của mình, thay cho các app như MyFitnessPal hay Hevy. Nó có giao diện web, app điện thoại, và có thể đồng bộ từ đồng hồ hoặc nền tảng sức khoẻ. Cài bằng Docker Compose với vài lệnh, nhưng bạn phải tự điền vài khoá bảo mật, nên hơi cần chút quen tay với terminal.
SparkyFitness là một nền tảng theo dõi sức khoẻ và thể hình mà bạn tự cài trên máy chủ của mình (self-hosted). Nó gom việc ghi ăn uống, tập luyện, nước uống, giấc ngủ, nhịn ăn, tâm trạng và số đo cơ thể vào một chỗ. Dữ liệu nằm trên hạ tầng do bạn quản lý, không phải trên dịch vụ của bên thứ ba. Tác giả định vị nó như một lựa chọn thay thế cho MyFitnessPal, Flo, Hevy, Shotsy và những app tương tự.
Nếu bạn đang trả tiền cho hai, ba app khác nhau (một app đếm calo, một app ghi buổi tập, một app theo dõi giấc ngủ) mà vẫn không có báo cáo chung, repo này đáng để thử. Nó cũng hợp với gia đình muốn cùng theo dõi trong một hệ thống, và với những ai ngại để dữ liệu sức khoẻ nằm trên máy chủ của người khác.
Điểm đáng giá nhất là độ phủ: một hệ thống gồm máy chủ, web, app iOS/Android và app cho Apple Watch/Wear OS, cộng với việc đồng bộ từ nhiều dịch vụ như Apple Health, Google Health Connect, Fitbit, Garmin Connect. Repo hiện có khoảng 6.777 sao và 468 fork, và vẫn được cập nhật trong vài tháng gần đây.
Về giấy phép: README ghi rõ SparkyFitness là source-available, không phải mã nguồn mở. Giấy phép là phi thương mại, muốn dùng cho mục đích thương mại thì cần xin phép tác giả. Dùng cá nhân và trong gia đình thì không vướng, còn nếu định dùng cho doanh nghiệp bạn nên đọc kỹ file LICENSE trong repo trước.
CodeWithCJ/SparkyFitness
SparkyFitness là nền tảng tự cài để theo dõi ăn uống, tập luyện, nước, giấc ngủ và chỉ số cơ thể cho cả gia đình, dữ liệu nằm trên máy chủ của bạn.
I.SparkyFitness làm được gì
Dưới đây là những tính năng chính theo README, kèm lợi ích thực tế khi dùng.
A.Theo dõi nhiều thứ trong một app
Bạn ghi được dinh dưỡng, tập luyện, lượng nước, giấc ngủ, nhịn ăn, tâm trạng và số đo cơ thể. Lợi ích là không phải nhảy qua lại giữa nhiều app, và có thể nhìn các số liệu cạnh nhau. Ví dụ bạn xem được tuần ngủ ít thì cân nặng và lượng ăn có khác đi không.
B.Đặt mục tiêu và check-in hằng ngày
Bạn đặt mục tiêu và check-in mỗi ngày. Việc này giúp biến số liệu rời rạc thành một thói quen có điểm mốc để so sánh.
C.Biểu đồ và báo cáo dài hạn
App có biểu đồ tương tác và báo cáo theo thời gian. README cũng nói xem toàn bộ lịch sử và báo cáo theo khoảng ngày tuỳ chọn là miễn phí, không bị khoá sau gói trả tiền như ở một số app khác.
D.Nhiều hồ sơ, chia sẻ trong gia đình
Hệ thống hỗ trợ nhiều hồ sơ người dùng và quyền truy cập cho gia đình. Bảng so sánh trong README nói có 7 quyền chia sẻ chi tiết. Lưu ý chính README xếp mục Family & Friends vào nhóm beta, nên có thể còn lỗi.
E.Đồng bộ từ thiết bị và dịch vụ
README liệt kê rất nhiều nguồn: Apple Health (iOS), Google Health Connect (Android), Fitbit, Garmin Connect, Withings, Polar Flow, Oura, Hevy, Strava (mới test một phần), COROS, Intervals.ICU và nhiều dịch vụ khác. Về dinh dưỡng có OpenFoodFacts, USDA, Fatsecret, Nutritionix, Mealie, Tandoor… Dữ liệu như bước chân, buổi tập, giấc ngủ, cân nặng được đẩy về máy chủ của bạn.
F.Bảo mật tài khoản
README nhắc tới OIDC, TOTP, Passkey và MFA. Nghĩa là bạn có thể bật đăng nhập hai lớp thay vì chỉ dùng mật khẩu.
G.SparkyAI (beta)
Đây là giao diện trò chuyện để ghi dữ liệu và xem lại tiến độ. Bạn có thể ghi món ăn, bài tập, chỉ số cơ thể, số bước bằng cách nhắn tin, hoặc tải ảnh món ăn lên để tự ghi bữa. Phần này đang ở dạng beta. Bảng so sánh còn nhắc tới MCP server và khả năng dùng mô hình AI của riêng bạn (bring your own LLM).
H.Nhập CSV và xuất dữ liệu
README nói bạn nhập được CSV và xuất dữ liệu miễn phí. Khi chuyển từ app cũ sang, hoặc sau này muốn rời đi, bạn không bị kẹt.
II.Cần chuẩn bị gì
Theo README, cách tự cài dùng Docker Compose. Vậy bạn cần:
- Một máy hoặc máy chủ chạy được Docker và lệnh
docker compose. README không nói cụ thể hệ điều hành hay cấu hình tối thiểu, nên mình không đưa ra con số nào ở đây. Phần yêu cầu chi tiết nằm ở trang tài liệu của dự án. - Công cụ
curlđể tải file, vàopensslnếu bạn tự sinh khoá bằng lệnh (cách Option A bên dưới thì không cần). - Khả năng điền một vài giá trị vào file
.env: mật khẩu cơ sở dữ liệu, khoá mã hoá API, khoá xác thực và địa chỉ bạn sẽ mở app. - Một thư mục trống để đặt file cấu hình.
README không yêu cầu API key của bên thứ ba cho phần cài cơ bản, và không nhắc tới GPU. Các tính năng đồng bộ thiết bị hay AI thì có thể cần tài khoản hoặc khoá riêng của từng dịch vụ. Phần đó README không nói chi tiết, hãy xem trang tài liệu.
Nếu bạn không rành kỹ thuật, README có mục Cloud: triển khai một bản chạy sẵn trên dịch vụ của bên thứ ba. README nói đây là các dịch vụ độc lập và khuyên bạn tự tìm hiểu để chọn cái hợp. Bài này tập trung vào cách tự cài.
III.Cài đặt từng bước
- Tạo thư mụcTạo thư mục sparkyfitness và đi vào đó
- Tải docker-compose.ymlLấy file cấu hình chạy chính thức từ repo
- Tạo file .envDùng trình tạo trên web hoặc tải mẫu về
- Thay giá trị mặc địnhĐiền mật khẩu, khoá bí mật và địa chỉ truy cập
- Khởi độngKéo image về và chạy nền bằng Docker Compose
A.Tạo thư mục làm việc
Mở terminal ở nơi bạn muốn đặt dữ liệu cấu hình, rồi chạy:
mkdir sparkyfitness && cd sparkyfitnessLệnh này tạo thư mục sparkyfitness và đi vào đó. Người dùng Windows hay vấp ở đây: dấu && không chạy trong Windows PowerShell bản cũ. Bạn có thể chạy hai lệnh riêng (mkdir sparkyfitness, rồi cd sparkyfitness), hoặc dùng Git Bash/WSL.
B.Tải file docker-compose.yml
curl -L -o docker-compose.yml https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/docker-compose.prod.ymlLệnh tải file cấu hình chạy bản production từ repo, lưu thành docker-compose.yml trong thư mục hiện tại. Trên PowerShell, curl có thể là bí danh của một lệnh khác, nên nếu lỗi hãy gõ curl.exe thay cho curl.
C.Tạo file .env
README đưa ra ba cách, bạn chọn một.
Option A (README khuyên dùng): dùng trình tạo .env chạy ngay trên trình duyệt, tự điền sẵn các khoá bảo mật. Địa chỉ là https://codewithcj.github.io/SparkyFitness/install/env-generator. Bạn tạo xong thì lưu nội dung thành file .env đặt cạnh docker-compose.yml.
Option B: mẫu tối giản, chỉ 5 giá trị, còn lại dùng mặc định. README nói đủ cho đa số bản tự cài:
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.simple.exampleOption C: bản đầy đủ, liệt kê mọi biến (đã comment sẵn kèm giá trị mặc định). README bảo nên bắt đầu từ đây nếu bạn cần SSO, SMTP, cơ sở dữ liệu ngoài hoặc reverse proxy. Trong README lệnh này đang để dạng comment, bạn bỏ dấu # để chạy:
curl -L -o .env https://raw.githubusercontent.com/CodeWithCJ/SparkyFitness/main/docker/.env.exampleD.Thay các giá trị giữ chỗ
Bỏ qua bước này nếu bạn dùng Option A, vì trình tạo đã điền sẵn. Với Option B hoặc C, mở file .env bằng trình soạn thảo văn bản và thay bốn giá trị sau (README nói rõ máy chủ sẽ từ chối khởi động nếu bạn để nguyên giá trị mẫu):
SPARKY_FITNESS_DB_PASSWORD: một mật khẩu mạnh bất kỳ.SPARKY_FITNESS_API_ENCRYPTION_KEY: sinh bằngopenssl rand -hex 32(ra 64 ký tự hex).BETTER_AUTH_SECRET: sinh bằngopenssl rand -base64 32(ra 44 ký tự).SPARKY_FITNESS_FRONTEND_URL: địa chỉ bạn sẽ dùng để mở app.
Các lệnh sinh khoá, đúng như README:
openssl rand -hex 32
openssl rand -base64 32Mỗi lệnh in ra một chuỗi ngẫu nhiên, bạn chép chuỗi đó vào đúng biến tương ứng. Đừng dùng chung một chuỗi cho cả hai biến, và đừng đăng file .env lên mạng.
File .env chứa mật khẩu và khoá mã hoá. Đừng chụp màn hình gửi người khác, đừng đẩy lên GitHub. Hãy sao lưu riêng một bản ở nơi an toàn: mất khoá mã hoá thì có thể không đọc lại được dữ liệu đã lưu.
E.Khởi động ứng dụng
docker compose pull && docker compose up -ddocker compose pull tải các image về, docker compose up -d khởi động các dịch vụ chạy nền. Lần đầu có thể mất vài phút tuỳ tốc độ mạng. Chạy lệnh trong đúng thư mục có docker-compose.yml và .env, nếu không Docker sẽ báo không tìm thấy file.
Cách cài khác (reverse proxy, các phương pháp triển khai khác) nằm ở trang tài liệu của dự án: https://codewithcj.github.io/SparkyFitness/.
IV.Kiểm tra đã chạy được chưa
Theo README, sau khi chạy xong bạn mở trình duyệt và vào:
http://localhost:3004Nếu thấy giao diện SparkyFitness hiện ra là máy chủ đã chạy. Nếu bạn đặt SPARKY_FITNESS_FRONTEND_URL thành một địa chỉ khác (ví dụ tên miền riêng), hãy dùng đúng địa chỉ đó.
Bạn cũng có thể xem trạng thái các container:
docker compose psLệnh này liệt kê các dịch vụ đang chạy. Nếu có dịch vụ thoát liên tục, xem phần lỗi hay gặp bên dưới. README chưa mô tả chi tiết bước tạo tài khoản đầu tiên, nên khi vào giao diện hãy làm theo màn hình đăng ký hoặc đăng nhập hiện ra, hoặc xem hướng dẫn trong trang tài liệu.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng README mô tả. Những chỗ README chưa hướng dẫn từng bước thì mình chỉ nói hướng đi chung và nhắc bạn xem tài liệu.
A.Cả nhà cùng theo dõi trong một hệ thống
Bối cảnh: nhà bạn có bốn người. Bố muốn giảm cân, mẹ theo dõi lượng nước, con đang tập thể thao. Trước đây mỗi người dùng một app và không ai thấy số liệu của ai.
Cách làm: bạn cài SparkyFitness trên một máy trong nhà, tạo hồ sơ cho từng người và dùng tính năng quyền truy cập cho gia đình. README nói có nhiều hồ sơ và phân quyền chi tiết, nhưng cũng ghi tính năng Family & Friends đang beta, nên hãy thử với số liệu ít quan trọng trước.
Kết quả: mỗi người có không gian riêng, bạn quyết định ai được xem phần nào. Không ai phải trả tiền thuê bao riêng.
Một app cho cả nhà, dữ liệu nằm ngay trong máy của mình, đó là lý do đáng để bỏ nửa tiếng cài đặt.
Ông T
B.Người đeo đồng hồ muốn gom dữ liệu về một chỗ
Bối cảnh: bạn là nhân viên văn phòng chạy bộ buổi sáng với đồng hồ Garmin hoặc Fitbit, còn buổi tối thì tự ghi bữa ăn. Dữ liệu tập nằm ở app của hãng, dữ liệu ăn nằm ở chỗ khác.
Cách làm: trong SparkyFitness, bạn kết nối dịch vụ đồng bộ tương ứng. README liệt kê Garmin Connect, Fitbit, Withings, Polar Flow, Oura và nhiều nguồn khác, còn trên điện thoại thì dùng Apple Health (iOS) hoặc Google Health Connect (Android). Cách kết nối cụ thể từng dịch vụ README không ghi, bạn xem hướng dẫn trong trang tài liệu hoặc wiki của dự án (README có link cho iOS và Android).
Kết quả: số bước, buổi tập, giấc ngủ, cân nặng tự đổ về máy chủ của bạn. Bạn xem biểu đồ dài hạn và đối chiếu với lượng ăn trong cùng một báo cáo.
C.Ghi bữa ăn bằng cách trò chuyện
Bối cảnh: bạn bận, không muốn mở danh sách thực phẩm tìm từng món. Bạn muốn nhắn một câu là xong.
Cách làm: dùng SparkyAI (beta). README nói bạn có thể ghi món ăn, bài tập, chỉ số cơ thể và số bước qua chat, hoặc tải ảnh món ăn lên để ghi tự động. Một câu mẫu để thử:
Sáng nay mình ăn hai quả trứng ốp la với một lát bánh mì, uống một ly nước cam.Kết quả mong đợi: app ghi các món vào nhật ký ngày hôm nay. Vì đây là tính năng beta, bạn nên xem lại các con số calo và khẩu phần trước khi tin hẳn. README chưa nói rõ cần cấu hình nhà cung cấp AI nào, nên bước thiết lập AI hãy xem trong tài liệu.
D.Dev tự host và tự quản dữ liệu
Bối cảnh: bạn là lập trình viên mới, có một máy chủ nhỏ hoặc homelab và muốn có công cụ thể hình riêng, không phụ thuộc dịch vụ ngoài.
Cách làm: cài như phần trên, sau đó nhập lịch sử từ app cũ qua CSV (README nói có hỗ trợ nhập CSV) và đặt reverse proxy nếu muốn truy cập từ ngoài (xem Option C và trang tài liệu). Nếu muốn đọc mã nguồn hoặc đóng góp, repo có thư mục riêng cho frontend, server và app di động, cùng hướng dẫn phát triển ở trang tài liệu.
Kết quả: bạn có một hệ thống chạy trên hạ tầng của mình, có thể xuất dữ liệu bất cứ lúc nào.
VI.Lỗi hay gặp và cách xử lý
A.Máy chủ không chịu khởi động
README nói rõ máy chủ từ chối chạy khi các giá trị giữ chỗ trong .env vẫn còn nguyên (mật khẩu DB, khoá mã hoá, khoá xác thực). Cách xử lý: mở .env, thay đủ bốn giá trị đã nêu ở trên, rồi chạy lại docker compose up -d. Xem lý do cụ thể bằng docker compose logs.
B.Gõ lệnh báo không tìm thấy docker hoặc compose
Nghĩa là máy chưa cài Docker, hoặc cài rồi nhưng chưa bật. Cách xử lý: cài Docker theo hướng dẫn chính thức của Docker cho hệ điều hành của bạn, mở lại terminal và thử docker compose version trước khi chạy tiếp.
C.Không vào được http://localhost:3004
Có vài khả năng: các container chưa chạy xong, hoặc cổng bị chiếm, hoặc bạn đặt SPARKY_FITNESS_FRONTEND_URL khác với địa chỉ đang gõ trên trình duyệt. Cách xử lý: chạy docker compose ps xem dịch vụ nào đang lỗi, đối chiếu lại địa chỉ trong .env, và xem log. Nếu vẫn kẹt, README gợi ý đăng issue hoặc discussion trên GitHub, hoặc hỏi trong Discord của dự án.
D.Nâng cấp xong thì có gì đó hỏng
README cảnh báo dự án đang phát triển tích cực và có thể có thay đổi phá vỡ giữa các bản phát hành. Vì vậy README khuyên không nên bật tự động cập nhật container, và luôn đọc ghi chú phát hành (file CHANGELOG.md trong repo) trước khi nâng cấp. Trước khi nâng cấp hãy sao lưu dữ liệu. Repo có sẵn các file db_backup.sh và DB Backup.cmd ở thư mục gốc, nhưng README không hướng dẫn cách dùng, nên hãy đọc nội dung file hoặc tài liệu trước khi chạy.
E.Chatbot AI hoặc chia sẻ gia đình chạy chưa đúng ý
README xếp AI Chatbot, Family & Friends access và tài liệu API vào nhóm beta, có thể còn lỗi hoặc thiếu tính năng. Cách xử lý: đừng dựa hoàn toàn vào các tính năng này cho dữ liệu quan trọng, kiểm tra lại số liệu thủ công, và báo lỗi cho tác giả qua GitHub issues nếu gặp.
VII.Có nên dùng không
Điểm mạnh:
- Dữ liệu sức khoẻ nằm trên máy chủ do bạn kiểm soát.
- Gom dinh dưỡng, tập luyện, giấc ngủ, nhịn ăn và thuốc vào một nơi, thay vì nhiều app.
- Đồng bộ được từ nhiều thiết bị và dịch vụ, có app di động và app cho đồng hồ.
- Hỗ trợ nhiều hồ sơ, hợp với gia đình.
- Có xuất dữ liệu, ít bị khoá chặt vào một nhà cung cấp.
Giới hạn bạn cần biết:
- Bạn phải tự cài và tự bảo trì máy chủ, tự sao lưu và tự nâng cấp có cân nhắc. Cài khá nhanh nhưng không phải kiểu bấm một nút.
- Dự án đang phát triển, có thể có thay đổi phá vỡ giữa các bản.
- Một số tính năng còn beta (chatbot AI, Family & Friends, tài liệu API).
- Giấy phép là phi thương mại, dùng cho kinh doanh cần xin phép.
- Bảng so sánh trong README do chính dự án viết, và chính README cũng nói một số ô có thể đã lỗi thời. Bạn nên đọc nó như thông tin tham khảo, không phải kết luận khách quan.
Khi nào nên chọn cách khác: nếu bạn chỉ cần ghi calo vài lần mỗi tuần và không muốn quản lý máy chủ, một app có sẵn trên cửa hàng ứng dụng có thể tiện hơn. Nếu bạn muốn dùng cho dịch vụ thương mại (ví dụ phòng tập, huấn luyện viên có thu phí), hãy hỏi tác giả về giấy phép trước. Còn nếu bạn ngại kỹ thuật nhưng vẫn muốn bản tự quản, README có hướng triển khai trên dịch vụ cloud của bên thứ ba.
Tóm lại, SparkyFitness hợp với người muốn giữ dữ liệu sức khoẻ trong tay mình, hoặc cả nhà muốn dùng chung một hệ thống, và chấp nhận bỏ chút thời gian cài đặt.
Câu hỏi thường gặp
SparkyFitness có miễn phí không?
README nói app không thu phí thuê bao và không quảng cáo, kể cả báo cáo toàn bộ lịch sử. Tuy nhiên giấy phép là phi thương mại: muốn dùng cho mục đích thương mại thì cần xin phép tác giả. Bạn vẫn phải tự lo chi phí máy chủ hoặc điện nếu tự cài.
Cài SparkyFitness có cần GPU không?
README không nhắc tới GPU hay cấu hình phần cứng tối thiểu. Cách cài chính là Docker Compose. Thông tin cấu hình chi tiết chưa có trong README, bạn xem thêm ở trang tài liệu của dự án.
Chạy được trên Windows không?
README không nêu rõ danh sách hệ điều hành. Cách cài dựa trên Docker Compose và các lệnh như curl, nên bạn cần môi trường chạy được các lệnh đó. Trên Windows, dấu && và lệnh curl có thể khác trong PowerShell, bạn có thể chạy từng lệnh riêng hoặc dùng Git Bash/WSL.
Dữ liệu của mình có an toàn không?
README nhấn mạnh đây là bản tự cài, ưu tiên quyền riêng tư: dữ liệu lưu trên hạ tầng bạn kiểm soát, không dựa vào dịch vụ bên thứ ba. App hỗ trợ OIDC, TOTP, Passkey, MFA. Mức an toàn thực tế còn tuỳ cách bạn đặt khoá, bảo vệ máy chủ và sao lưu.
SparkyFitness khác gì MyFitnessPal hay Hevy?
Theo README, khác biệt chính là tự cài, không thuê bao, và gom dinh dưỡng, tập luyện, giấc ngủ, nhịn ăn và thuốc vào một nơi. Nó cũng đồng bộ từ nhiều dịch vụ và có chia sẻ trong gia đình. Lưu ý bảng so sánh do chính dự án viết, và README thừa nhận một số ô có thể đã cũ.
Tính năng AI có dùng được ngay không?
README ghi SparkyAI là tính năng tuỳ chọn và đang ở dạng beta. Nó cho phép ghi món ăn, bài tập, chỉ số cơ thể qua chat, và ghi bữa từ ảnh. Cách cấu hình nhà cung cấp AI chưa có trong README, nên bạn cần xem tài liệu của dự án.
Có nên bật tự động cập nhật không?
Không. README nói dự án phát triển tích cực, có thể có thay đổi phá vỡ giữa các bản và không khuyến khích tự động cập nhật container. Bạn nên đọc ghi chú phát hành trước khi nâng cấp.


