Skip to content
BranchesTags

Repository files navigation

zalo-linux-auto-pack

zalo-linux-auto-pack là bộ cài đặt tự động giúp chạy Zalo PC bản Windows trên Linux thông qua Bottles/Wine.

Dự án thuộc VN Linux Family (VNLF) và được tách ra từ nhu cầu thực tế trong quá trình phát triển CaramOS: CaramOS cần một cách ổn định để cài Zalo trên Linux, nhưng thay vì giữ riêng trong CaramOS, VNLF tách thành một gói độc lập để các distro Linux khác và cộng đồng Việt Nam có thể dùng lại.

Trạng thái: đang phát triển/thử nghiệm, đã test thực tế trên Ubuntu 22.04.5 LTS.

Mục tiêu

Repo này hướng tới trải nghiệm:

sudo bash install.sh

và script sẽ tự động xử lý nhiều việc nhất có thể:

  • Nhận dạng distro Linux hiện tại
  • Cài các gói hệ thống cần thiết theo distro
  • Cài Flatpak và Bottles từ Flathub
  • Pin Bottles Flatpak về branch stable
  • Tạo bottle riêng tên zalo
  • Bootstrap runner/component Bottles khi CLI chưa initial setup GUI
  • Cài/cấu hình font để Zalo hiển thị tiếng Việt tốt hơn
  • Dùng sẵn bộ cài Zalo PC ổn định trong repo
  • Chạy Zalo installer trong Bottles/Wine
  • Mặc định cài silent để tránh installer GUI bị treo/ẩn
  • Tạo lệnh zalo và desktop launcher
  • Ghi chú rõ các giới hạn hiện tại của Wine

Vì sao repo có sẵn ZaloSetup-26.5.10.exe?

Khác với các script chỉ tải bản mới nhất từ internet, repo này mặc định đóng kèm bộ cài đã test ổn định:

ZaloSetup-26.5.10.exe

Lý do:

  1. Tái lập được kết quả: người dùng và maintainer cùng test trên một bản Zalo cụ thể.
  2. Tránh update bất ngờ: nếu Zalo đổi installer mới làm hỏng Wine/Bottles, repo vẫn chạy bản đã biết là hoạt động được.
  3. Phù hợp với CaramOS: distro cần một flow cài đặt ổn định, không phụ thuộc hành vi thay đổi của upstream mỗi ngày.
  4. Khi Zalo update: VNLF sẽ test lại, sau đó cập nhật file installer trong repo và bump version tài liệu.

Lưu ý: Zalo là phần mềm thuộc sở hữu của Zalo/VNG. Repo này không chỉnh sửa Zalo, chỉ cung cấp automation cài đặt trên Linux. Nếu có yêu cầu pháp lý/phân phối lại, hướng thay thế là tải installer từ URL chính thức trong lúc cài.

Cách dùng nhanh

git clone https://github.com/VN-Linux-Family/zalo-linux-auto-pack.git
cd zalo-linux-auto-pack
sudo bash install.sh

Installer bắt buộc phải có sẵn trong repo:

ZaloSetup-26.5.10.exe

Nếu thiếu file này, script sẽ dừng lại để đảm bảo mọi người dùng đúng bản Zalo đã được VNLF test.

Sau khi cài xong:

zalo

Lệnh zalo sẽ tách GUI khỏi terminal, nên terminal trả prompt lại ngay trong khi cửa sổ Zalo vẫn mở.

Cài sạch / reset toàn bộ

Xoá bottle/prefix và cài lại từ đầu:

sudo bash uninstall.sh --remove-bottles
ZALO_RESET=1 sudo -E bash install.sh

Xoá sạch hơn, bao gồm cả Bottles Flatpak và package Flatpak:

sudo bash uninstall.sh --remove-bottles --remove-flatpak
ZALO_RESET=1 sudo -E bash install.sh

Nếu muốn lưu log khi cài lại:

ZALO_RESET=1 sudo -E bash install.sh 2>&1 | tee install-clean.log

Chế độ cài silent và interactive

Mặc định script chạy Zalo installer ở chế độ silent:

ZALO_SILENT=1

Nghĩa là installer được gọi với tham số NSIS:

/S

Vì vậy bạn sẽ không thấy wizard cài đặt Zalo. Nếu cài thành công, khi chạy zalo app sẽ mở thẳng màn hình đăng nhập QR.

Lý do mặc định silent:

  • Ít phụ thuộc GUI Wine/Bottles hơn
  • Tránh installer bị ẩn sau cửa sổ khác
  • Tránh treo ở bước cuối dù Zalo đã cài xong
  • Phù hợp với mục tiêu auto-pack/tự động hoá

Nếu muốn mở bảng cài đặt Zalo để xem wizard:

ZALO_RESET=1 ZALO_SILENT=0 sudo -E bash install.sh 2>&1 | tee install-interactive.log

Hoặc chạy installer thủ công trong bottle hiện tại:

flatpak run --command=bottles-cli app/com.usebottles.bottles/x86_64/stable run \
  -b zalo \
  -e "$(pwd)/ZaloSetup-26.5.10.exe"

Không thêm /S nếu muốn GUI installer hiện ra.

Debug nhanh

Log install được ghi vào:

~/.local/state/zalo-linux-auto-pack/logs/install-*.log

Log chạy Zalo được ghi vào:

~/.local/state/zalo-linux-auto-pack/logs/zalo-run-*.log

Xem log chạy Zalo mới nhất:

tail -n 160 "$(ls -t ~/.local/state/zalo-linux-auto-pack/logs/zalo-run-*.log | head -n 1)"

Bật trace shell chi tiết khi cần debug installer:

ZALO_DEBUG=1 ZALO_RESET=1 sudo -E bash install.sh 2>&1 | tee install-debug.log

Kiểm tra syntax sau khi sửa code:

bash -n install.sh uninstall.sh lib/*.sh libexec/*.sh templates/zalo-launcher.sh

Distro hỗ trợ

Script được thiết kế để tự nhận dạng distro qua /etc/os-release.

Nhóm distro Trạng thái Package manager
Ubuntu/Debian/Linux Mint/Pop!_OS ✅ Ưu tiên test apt
Fedora ⚠️ Cần test thêm dnf
Arch/Manjaro/EndeavourOS ⚠️ Cần test thêm pacman
openSUSE ⚠️ Cần test thêm zypper
Distro khác ⚠️ Best-effort script cố tự cài Flatpak, nếu không nhận diện được thì báo lệnh cần chạy

Flatpak là backend bắt buộc vì Bottles được cài qua Flathub. Người dùng không cần cài Flatpak trước; install.sh sẽ tự nhận dạng distro và tự cài Flatpak bằng package manager tương ứng (apt, dnf, pacman, zypper) nếu có thể.

Repo pin Bottles về full Flatpak ref:

app/com.usebottles.bottles/x86_64/stable

Việc này tránh lỗi Flatpak resolve nhầm branch master sau khi clean reinstall.

Những gì hoạt động tốt

Tính năng Trạng thái Ghi chú
Đăng nhập QR ✅ Đã test
Chat văn bản ✅ Đã test
Gửi/nhận file ✅ Đã test cơ bản
Gửi ảnh/video ✅ Đã test cơ bản
Gọi thoại ✅ Có thể hoạt động tùy máy
Font tiếng Việt ✅ Cần font fix trong script
Đồng bộ tin nhắn ✅ Phụ thuộc Zalo

Giới hạn đã biết

Đây là giới hạn của Wine/Bottles hiện tại, không phải lỗi riêng của zalo-linux-auto-pack.

Tính năng Trạng thái Nguyên nhân
Emoji màu ❌ Wine DirectWrite chưa hỗ trợ đầy đủ color font/emoji
Camera/video call ❌ Wine chưa có bridge ổn định từ Windows camera API sang Linux V4L2
Zalo Web call ❌ Zalo Web không hỗ trợ gọi

Debug thực tế từng thấy với emoji:

dwritefontface5_HasVariations: stub

Kiến trúc runtime

Zalo PC Windows (.exe)
        ↓
Electron/Chromium trong Zalo
        ↓
Windows API: DirectWrite, GDI, WinHTTP, Media Foundation...
        ↓
Wine/Soda runner
        ↓
Bottles quản lý prefix + DXVK/VKD3D + config
        ↓
Flatpak sandbox
        ↓
Linux desktop

Wine, Bottles, Soda là gì?

  • Wine: lớp tương thích dịch Windows API sang Linux API, không phải máy ảo.
  • Bottles: giao diện/quản lý Wine prefix, runner, dependency, config.
  • Soda: runner Wine custom của Bottles, dựa trên Wine + Staging + Proton/TkG patches.

Kiến trúc code

Code installer giữ Bash là ngôn ngữ chính, nhưng đã tách các phần dễ rối ra file riêng:

  • lib/*.sh: orchestration, config, runtime helpers
  • libexec/*: helper thực thi cụ thể
  • templates/*: file được render ra hệ thống

Không còn nhúng các block lớn kiểu:

  • run_as_user bash -c '...'
  • python3 - <<'PY'
  • heredoc dài để generate launcher/desktop

Phần Python còn lại là helper riêng:

libexec/bootstrap-components.py

Helper này chạy bằng python3 bên trong Flatpak Bottles vì cần đọc YAML manifest component của Bottles và module yaml có sẵn trong runtime Bottles.

Cấu trúc repo

zalo-linux-auto-pack/
├── ZaloSetup-26.5.10.exe
├── install.sh                       # entrypoint nhỏ, source các module trong lib/
├── uninstall.sh                     # gỡ launcher/bottle/flatpak tùy option
├── lib/
│   ├── constants.sh                 # biến cấu hình, APP_ID, APP_REF, runner, version
│   ├── logging.sh                   # log màu, log file, trap lỗi
│   ├── runtime.sh                   # chạy lệnh root/user/flatpak, cleanup Wine
│   ├── distro.sh                    # nhận dạng distro và cài package hệ thống
│   ├── flatpak.sh                   # cấu hình Flatpak/Bottles
│   ├── bottles.sh                   # runner, component, bottle, dependency
│   ├── bottle_config.sh             # cấu hình bottle.yml/graphics/env
│   ├── fonts.sh                     # copy font và registry tweak
│   ├── templates.sh                 # render template đơn giản
│   ├── zalo.sh                      # chọn installer, cài Zalo, tạo launcher
│   └── main.sh                      # workflow tổng install_zalo_linux_auto_pack
├── libexec/
│   ├── bootstrap-runner.sh          # tải/extract runner Bottles fallback
│   └── bootstrap-components.py      # bootstrap dxvk/vkd3d/nvapi/latencyflex
├── templates/
│   ├── zalo-launcher.sh             # template /usr/local/bin/zalo
│   └── zalo-linux-auto-pack.desktop # template desktop entry
├── docs/
│   └── install-zalo-bottles-ubuntu.md
├── README.md
├── SECURITY.md
└── LICENSE

Launcher zalo

Sau khi cài, script tạo:

/usr/local/bin/zalo

Launcher dùng:

C:\windows\command\start.exe /unix <Zalo.exe>

thông qua Bottles CLI. Cách này giúp Wine spawn app GUI tách khỏi terminal và tránh lỗi Electron/Node từng gặp khi chạy thẳng Zalo.exe qua bottles-cli:

uv_pipe_open

Launcher cũng ghi log mỗi lần chạy vào:

~/.local/state/zalo-linux-auto-pack/logs/zalo-run-*.log

Tài liệu chi tiết

Xem thêm:

Quan hệ với CaramOS

CaramOS là dự án distro/hệ sinh thái Linux của VN Linux Family.

Trong quá trình phát triển CaramOS, nhu cầu chạy Zalo trên Linux là rất thực tế với người dùng Việt Nam. Thay vì để logic cài Zalo nằm cứng trong CaramOS, VNLF tách phần này thành zalo-linux-auto-pack để:

  • CaramOS có thể dùng lại như một module độc lập
  • Người dùng Ubuntu/Fedora/Arch/openSUSE cũng có thể dùng
  • Cộng đồng có thể đóng góp fix riêng cho Zalo mà không cần đụng vào core distro
  • Dễ theo dõi version Zalo, Wine, Bottles và các workaround

Repo gốc CaramOS: https://github.com/VN-Linux-Family/CaramOS

Đóng góp

Pull request/issue rất được hoan nghênh, đặc biệt các phần:

  • Test trên Fedora/Arch/openSUSE
  • Cải thiện auto-detect distro
  • Cải thiện font rendering
  • Tìm workaround camera/emoji trên Wine
  • Tạo desktop launcher đẹp hơn
  • Đóng gói thành module cho CaramOS

License

MIT — xem LICENSE.

About

No description, website, or topics provided.

Resources

Readme
MIT license

Security policy

Security policy
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages