Khi các dự án phát triển web ngày càng trở nên phức tạp, việc quản lý một lượng lớn các gói phụ thuộc (dependency packages) là điều không thể thiếu. Thay vì chỉ dựa vào các kho công khai như npmjs.org, việc thiết lập một kho NPM riêng tư (private registry) trong mạng nội bộ mang lại nhiều lợi ích đáng kể. Một kho NPM nội bộ giúp kiểm soát phiên bản của các gói phụ thuộc một cách chặt chẽ, đặc biệt đối với các thư viện nội bộ của công ty, đồng thời tăng tốc độ cài đặt và độ tin cậy. Sinopia là một giải pháp nhẹ nhàng và dễ triển khai để tạo kho NPM cá nhân.
1. Kiến trúc Hoạt động
Hệ thống hoạt động của Sinopia có thể hình dung như sau:
- Khi một máy khách (client) thực hiện yêu cầu cài đặt hoặc tải gói NPM, yêu cầu này sẽ được gửi đến máy chủ Sinopia.
- Nếu máy chủ được cấu hình xác thực, Sinopia sẽ kiểm tra quyền truy cập.
- Sau khi xác thực thành công, Sinopia sẽ tìm kiếm gói trong bộ nhớ đệm cục bộ (local cache) hoặc thư mục lưu trữ của nó.
- Nếu gói không tồn tại cục bộ, Sinopia sẽ chuyển tiếp yêu cầu đến các kho NPM thượng nguồn (uplinks) đã được cấu hình (ví dụ: npmjs.org). Khi gói được tải về từ thượng nguồn, nó sẽ được lưu trữ cục bộ cho các lần yêu cầu sau, giúp tăng tốc độ.
- Để đảm bảo tính sẵn sàng và khả năng chịu tải, Sinopia thường được triển khai dưới dạng cụm (cluster) và quản lý bằng các công cụ như PM2, cho phép cân bằng tải tự động giữa các tiến trình.
2. Cài đặt và Triển khai
Quá trình cài đặt Sinopia tương đối đơn giản. Bài viết này giả định bạn có quyền root trên máy chủ.
2.1. Cài đặt Node.js
Sinopia yêu cầu Node.js để hoạt động. Bạn có thể tải phiên bản phù hợp từ trang web chính thức của Node.js. Ví dụ, cho Linux 64-bit, bạn có thể tải file node-vX.Y.Z-linux-x64.tar.gz.
Đối với cài đặt offline, hãy đảm bảo giải nén file tarball trực tiếp trên hệ thống Linux để tránh các vấn đề liên quan đến quyền hoặc đường dẫn khi npm được sử dụng sau này. Sau khi giải nén, bạn cần thiết lập biến môi trường hoặc tạo symbolic link để các lệnh node và npm có thể được gọi từ bất kỳ đâu.
# Ví dụ: Giải nén và tạo symlink
# Giả sử bạn giải nén vào /opt/node-vX.Y.Z-linux-x64
sudo ln -s /opt/node-vX.Y.Z-linux-x64/bin/node /usr/local/bin/node
sudo ln -s /opt/node-vX.Y.Z-linux-x64/bin/npm /usr/local/bin/npm
2.2. Cài đặt Sinopia
Sau khi Node.js và npm đã được cài đặt và cấu hình thành công, bạn có thể cài đặt Sinopia. Nếu máy chủ của bạn nằm trong mạng nội bộ và cần proxy để truy cập internet, hãy cấu hình npm proxy trước:
# Cấu hình proxy cho npm (nếu cần)
npm config set proxy "http://username:password@proxy.domain.com:port"
npm config set https-proxy "http://username:password@proxy.domain.com:port"
# (Tùy chọn) Cấu hình registry gương trong nước để cài đặt nhanh hơn, ví dụ: Taobao
# npm config set registry "https://registry.npm.taobao.org"
# Cài đặt Sinopia toàn cục
npm install -g sinopia --no-optional --no-shrinkwrap
Tham số --no-optional và --no-shrinkwrap giúp tránh các lỗi biên dịch với các gói tùy chọn hoặc vấn đề với shrinkwrap file cũ. Sau khi cài đặt, bạn có thể kiểm tra:
sinopia
Nếu cài đặt thành công, bạn sẽ thấy thông báo tương tự như sau, chỉ ra file cấu hình và địa chỉ nghe mặc định:
warn --- config file - /root/.config/sinopia/config.yaml
warn --- http address - http://localhost:4873/
2.3. Cài đặt PM2
PM2 là một trình quản lý tiến trình production-ready cho các ứng dụng Node.js, rất hữu ích để giữ cho Sinopia luôn chạy và tự động khởi động lại khi có sự cố.
# Cài đặt pm2 toàn cục
npm install -g pm2
# Kiểm tra cài đặt
pm2 --version
Nếu cài đặt thành công, bạn sẽ thấy thông tin phiên bản PM2.
2.4. Khởi động Sinopia
Bạn có thể khởi động Sinopia trực tiếp hoặc thông qua PM2.
- Khởi động trực tiếp (chủ yếu để kiểm tra):
sinopia --listen http://0.0.0.0:4873/Thay
0.0.0.0bằng địa chỉ IP cụ thể nếu bạn muốn chỉ nghe trên một giao diện mạng nhất định, và4873là cổng mặc định. - Khởi động bằng PM2 (khuyến nghị cho môi trường production):
Đầu tiên, bạn cần cấu hình cổng và địa chỉ nghe trong file cấu hình Sinopia. Mặc định, file này nằm tại
~/.config/sinopia/config.yaml(ví dụ:/root/.config/sinopia/config.yamlnếu chạy bằng root). Mở file và thêm hoặc sửa dònglisten:# config.yaml listen: 0.0.0.0:4873 # Hoặc địa chỉ IP cụ thể của bạn, ví dụ: 192.168.1.100:4873Sau đó, khởi động Sinopia bằng PM2:
pm2 start $(which sinopia) --name "sinopia-registry"Lệnh này sẽ tìm đường dẫn của Sinopia và khởi động nó dưới tên tiến trình "sinopia-registry".
3. Cấu hình Sinopia (config.yaml)
File cấu hình chính của Sinopia là config.yaml, nằm trong thư mục ~/.config/sinopia/. Cùng với đó, có các file và thư mục quan trọng khác:
htpasswd: Chứa thông tin tài khoản người dùng và mật khẩu đã mã hóa (SHA1, Base64).storage: Thư mục lưu trữ các gói NPM cục bộ và bộ nhớ đệm. Đường dẫn của thư mục này có thể được cấu hình trongconfig.yaml:storage: /path/to/your/storage/directory/sinopia_data
3.1. Cấu hình Quyền truy cập
Một cấu hình phổ biến là cho phép tất cả người dùng tải gói nhưng chỉ cho phép các tài khoản cụ thể xuất bản gói. Dưới đây là ví dụ về cấu hình quyền trong mục packages:
packages:
# Áp dụng cho tất cả các gói
'*':
# Quyền đọc: Cho phép tất cả người dùng (bao gồm cả không xác thực) đọc gói
# Các giá trị có thể: "$all", "$anonymous", "$authenticated", hoặc tên người dùng/nhóm cụ thể
access: $all
# Quyền xuất bản: Chỉ cho phép người dùng 'internal_publisher' xuất bản gói
publish: internal_publisher # Bạn có thể liệt kê nhiều người dùng, ví dụ: ['user1', 'user2']
# Nếu gói không có sẵn cục bộ, chuyển tiếp yêu cầu đến kho 'npmjs'
proxy: npmjs
Để tăng cường bảo mật và kiểm soát, bạn nên vô hiệu hóa chức năng đăng ký tài khoản mới qua npm cli:
auth:
htpasswd:
file: ./htpasswd
# Số lượng người dùng tối đa được phép đăng ký. Đặt thành -1 để vô hiệu hóa đăng ký.
max_users: -1
3.2. Cấu hình Log
Sinopia cho phép bạn cấu hình nơi và cách thức ghi log:
logs:
- {type: stdout, format: pretty, level: http} # Ghi log ra console với định dạng đẹp, mức http
- {type: file, path: sinopia.log, level: info} # Ghi log ra file sinopia.log, mức info
3.3. Cấu hình Uplinks (Kho thượng nguồn)
Uplinks định nghĩa các kho NPM công khai mà Sinopia sẽ tìm kiếm gói nếu gói không tồn tại trong kho nội bộ của nó. Một cấu hình điển hình cho npmjs.org là:
uplinks:
npmjs:
url: https://registry.npmjs.org/
Nếu máy chủ Sinopia của bạn nằm trong mạng nội bộ và cần proxy để truy cập các uplink bên ngoài, bạn phải cấu hình biến môi trường proxy cho tiến trình Sinopia. Điều này thường được thực hiện trong script khởi động hoặc cấu hình PM2:
# Đặt biến môi trường proxy trước khi khởi động Sinopia bằng PM2
# Ví dụ: Thêm vào file .bashrc hoặc trong script khởi động
export HTTP_PROXY="http://username:password@proxy.domain.com:port"
export HTTPS_PROXY="http://username:password@proxy.domain.com:port"
export NO_PROXY="localhost,127.0.0.1,your_internal_domain.com"
4. Hướng dẫn Sử dụng
4.1. Cấu hình Kho NPM cho máy khách
Để các máy khách sử dụng kho Sinopia của bạn, họ cần trỏ registry của npm về địa chỉ của Sinopia:
npm config set registry http://your_sinopia_server_ip:4873/
Bạn có thể thay thế your_sinopia_server_ip và 4873 bằng địa chỉ và cổng thực tế của Sinopia. Để dễ dàng chuyển đổi giữa các registry khác nhau (ví dụ: kho công khai và kho nội bộ), bạn có thể sử dụng công cụ nrm (NPM Registry Manager).
4.2. Duy trì và Xuất bản Gói
Để xuất bản (publish) một gói lên kho Sinopia, bạn cần đăng nhập bằng tài khoản có quyền xuất bản đã cấu hình trong config.yaml.
npm login
Bạn sẽ được yêu cầu nhập tên người dùng, mật khẩu và email. Ví dụ:
Username: internal_publisher
Password: *********
Email: (this IS public) publisher@company.com
Logged in as internal_publisher on http://your_sinopia_server_ip:4873/
Sau khi đăng nhập thành công, điều hướng đến thư mục gốc của gói mà bạn muốn xuất bản (thư mục chứa package.json) và chạy lệnh:
npm publish
Nếu thành công, bạn sẽ thấy thông báo về tên và phiên bản gói đã được xuất bản (ví dụ: + my-package@1.0.0). Bạn cũng có thể kiểm tra trực tiếp qua trình duyệt bằng cách truy cập http://your_sinopia_server_ip:4873/ để xem danh sách các gói đã xuất bản.
Trong quá trình phát triển, việc duy trì file package.json chính xác là rất quan trọng. Đồng thời, hãy tuân thủ quy tắc Semantic Versioning (SemVer) 2.0.0 cho các gói của bạn và ghi lại các thay đổi trong file CHANGELOG.md để người dùng dễ dàng theo dõi các cập nhật khi duyệt gói trên giao diện web của Sinopia.