Nexus Repository OSS
Artifact proxy & cache — npm, Maven, PyPI, Docker registry mirror.
Bối cảnh & Lý do triển khai
Trong môi trường doanh nghiệp, developer và CI/CD pipeline liên tục tải dependency từ internet (npm, Maven, PyPI, Docker Hub, apt). Nexus Repository Manager đóng vai trò proxy cache và hosted repository: lần đầu tải về từ internet và cache lại, từ lần sau trả từ cache nội bộ — giảm băng thông, tăng tốc build, và đảm bảo tính nhất quán (internet package không bị xóa/thay đổi). Nexus cũng lưu trữ Docker image nội bộ, npm package tự viết, và Maven artifact của team.
K3s nodes được cấu hình để pull Docker image qua Nexus proxy thay vì trực tiếp từ Docker Hub, giúp tránh rate limit và tăng tốc deployment. Về phiên bản: từ 3.77.0 bản miễn phí "OSS" của Sonatype được đổi tên thành Nexus Repository Community Edition (tiêu đề bài giữ tên cũ), nên bài ghim image sonatype/nexus3:3.96.4 thay cho latest (phát hành 30/09/2026, được hỗ trợ đến 09/2027). Community Edition giới hạn 40.000 component và 100.000 request mỗi ngày; vượt một trong hai ngưỡng thì không thêm được component mới cho đến khi dưới cả hai (xem Usage Center trên trang chủ Nexus), và phải chấp nhận EULA của Community Edition (mục 3.2) thì mới tải lên/xuống component được. Mức này đủ cho lab; cơ sở dữ liệu mặc định là H2 nhúng, PostgreSQL chỉ cần khi mở rộng.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong doanh nghiệp | Quản lý tập trung tất cả artifact và dependency cho CI/CD |
| Tác dụng chính | Proxy cache npm/Maven/PyPI/Docker, lưu image nội bộ, kiểm soát supply chain |
| Nếu không triển khai | Build phụ thuộc internet hoàn toàn, rate limit Docker Hub, artifact mất khi registry xóa |
| Các service phụ thuộc vào đây | K3s (registry mirror), Gitea CI runners (build dependency) |
Phiên bản phần mềm sử dụng (đã xác minh 2026-10-15; cập nhật bài ngày 2026-10-15):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Hệ điều hành (nexus, VM267) | Ubuntu Server 24.04.5 LTS "Noble Numbat" | ISO ubuntu-24.04.5-live-server-amd64.iso (2026-09-09, releases.ubuntu.com/24.04), hỗ trợ chuẩn tới 04/2029. Gói mặc định: Linux 6.8, systemd 255, OpenSSL 3.0.13, netplan 1.0, Python 3.12, Nginx 1.24 |
| Nexus Repository Community Edition | 3.96.4 (image sonatype/nexus3:3.96.4, ghim) | Chạy trong container, JVM đi kèm bản phát hành nên không cài Java trên host và không phụ thuộc bản Ubuntu. Docker Hub đã có 3.97.0 (2026-10-14), bài chưa nâng |
| Docker Engine + Compose plugin | 29.9.1 (repo download.docker.com, suite noble) | Gói docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin; dùng lệnh docker compose. Số bản sẽ tăng theo thời gian |
| Nginx | 1.24.x (gói nginx của noble) | Reverse proxy HTTPS cho Web UI và registry |
| step-cli | 0.31.0 (step-cli_0.31.0-1_amd64.deb) | Giá trị dùng chung của lab |
| proxmox-backup-client-static | Gói từ repo pbs-client, suite trixie | Bản liên kết tĩnh, không phụ thuộc glibc của noble; chạy trên noble cần kiểm lại trên máy thật |
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| nexus (Nexus Repository OSS) · VM267 | 10.11.65.67 | 65 (SRV) · node3 | Máy chủ của bài — chạy Nexus Repository Community Edition 3.96.4 bằng Docker Compose (metrics tích hợp, không exporter); Nginx HTTPS, Docker hosted cổng 5000, proxy 5001–5004. |
| node3 (Proxmox VE) | 10.11.45.212 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM267; tải ISO Ubuntu Server 24.04.5 và tạo VM bằng Web UI hoặc qm create tại đây. |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | Phân giải nexus và docker-internal (alias thêm thủ công) về 10.11.65.67; bản ghi nexus có sẵn từ bài 12. |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp một chứng chỉ TLS cho Nginx (SAN nexus và docker-internal), gia hạn hằng tuần bằng step ca renew + cron (bài 13). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | LDAP outpost legacy-ldap (cổng 389) cho Nexus đăng nhập bằng tài khoản Authentik; bind bằng ldapservice (không MFA); nexus-admins và nexus-devs ánh xạ role nx-admin và nx-developer (bài 14). |
| K3s cluster (3 control plane + 3 worker) · VM 260–265 | 10.11.65.60–65 | 65 (SRV) · node1–node3 | Mọi node K3s (bài 28) dùng Nexus làm registry mirror: gộp mirror docker.io, gcr.io, quay.io, registry.k8s.io vào registries.yaml. |
| prometheus (Prometheus + Alertmanager) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Thêm job scrape nexus tới /service/rest/metrics/prometheus qua HTTPS cổng 443 (user prometheus) trong prometheus.yml rồi reload qua cổng 9090 (bài 15). |
| gitea (Gitea + Actions) · VM240 | 10.11.45.40 | 45 (MGMT) · node2 | Workflow Gitea Actions lấy dependency qua Nexus proxy (NPM_CONFIG_REGISTRY, PIP_INDEX_URL, Maven mirror) thay vì internet (bài 22). |
| pbs01 (PBS Primary) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Nhận backup file-level của /opt/nexus/data bằng token vm-backup@pbs!nexus, namespace vm-nexus (bài 04). |
| syno-primary (Synology NAS) | 10.11.45.16 | 45 (MGMT) · NAS | NAS chứa datastore syno-primary lưu backup của VM; script cron thứ Bảy 2:00, tạm dừng Nexus khi backup (bài 04). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local. docker-internal.hoatranlabs.local là alias DNS của nexus (cùng IP); Nginx tách hai vhost theo tên host.
Thông tin VM
| Thông số | Giá trị |
|---|---|
| VMID | 267 |
| Hostname | nexus |
| IP | 10.11.65.67/24 |
| Gateway | 10.11.65.1 |
| VLAN | 65 (VLAN_SRV) |
| vCPU | 4 |
| RAM | 8 GB |
| Disk | 30 GB hệ điều hành (scsi0, SSD vm-ceph) + 100 GB dữ liệu Nexus (scsi1, HDD vm-bulk, mount /opt/nexus/data) |
| OS | Ubuntu Server 24.04.5 LTS |
| Phân bổ node | node3 |
| URL chính | https://nexus.hoatranlabs.local |
| Docker internal | docker-internal.hoatranlabs.local (qua Nginx cổng 443; Nexus lắng nghe 5000 phía sau) |
create-lab-vms.sh thì scsi0 = 30 GB trên SSD vm-ceph, đĩa dữ liệu scsi1 = 100 GB trên HDD vm-bulk, mount tại /opt/nexus/data (mục 2.2); các số này khớp vms.csv và chỉ là trần danh nghĩa (thin provisioning), môi trường thật nên cấp lớn hơn (bài từng ghi 200 GB trên một đĩa) rồi nới bằng qm resize. Thư mục này chứa cả blob store lẫn cơ sở dữ liệu nhúng của Nexus nên cả hai nằm trên HDD, chấp nhận được cho lab; vì vm-bulk chỉ có vùng an toàn khoảng 200 GB dùng chung với Harbor, S3, Loki…, bài dùng cleanup policy 14 ngày (mục 3.3) để giữ blob store quanh mức khoảng 40 GB thật theo ước tính ở bài 07 mục 8.6 (đo lại bằng rbd du -p vm-bulk).
Tạo VM trên Proxmox
Tải Ubuntu ISO (nếu chưa có) · Tạo VM · Cài đặt Ubuntu 24.04
1.1 Tải Ubuntu ISO (nếu chưa có)
# Chạy trên Proxmox node node3
# 24.04.5 là bản point mới nhất tại thời điểm viết (2026-09-09); nếu đã có bản mới hơn, xem https://releases.ubuntu.com/24.04/
wget -O /var/lib/vz/template/iso/ubuntu-24.04.5-live-server-amd64.iso \
https://releases.ubuntu.com/24.04/ubuntu-24.04.5-live-server-amd64.iso
# Kiểm tra toàn vẹn: so kết quả với dòng tương ứng trong https://releases.ubuntu.com/24.04/SHA256SUMS
sha256sum /var/lib/vz/template/iso/ubuntu-24.04.5-live-server-amd64.iso
1.2 Tạo VM
Cách 1: Web UI Proxmox (GUI)
- VM ID:
267 - Name:
nexus - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph(SSD) - Disk size:
30 GiB, Cache:Write back, Discard: ☑ - Bấm Add để thêm đĩa thứ hai: Bus/Device
SCSI 1, Storage:vm-bulk(HDD), Disk size:100 GiB, Discard: ☑, SSD emulation: ☐ (đĩa dữ liệu Nexus; chưa có poolvm-bulkthì làm bài 07 mục 8.5 trước, hoặc tạm chọnvm-ceph)
- Sockets:
1, Cores:4, Type:x86-64-v2-AES
- Memory (MiB):
8192
- Bridge:
vmbr0, VLAN Tag:65, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
# Chạy trên node3
qm create 267 --name nexus --memory 8192 --cores 4 --sockets 1 \
--net0 virtio,bridge=vmbr0,tag=65 \
--scsi0 vm-ceph:30,cache=writeback \
--scsi1 vm-bulk:100,discard=on \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 --machine q35 --bios seabios \
--agent 1 --serial0 socket --vga serial0
qm start 267
1.3 Cài đặt Ubuntu 24.04
Kết nối qua Proxmox console (qm terminal 267):
- Language: English | Keyboard: English (US)
- Install type: Ubuntu Server (minimized)
- Network: DHCP tạm thời
- Storage: entire disk → LVM, không encrypt
- Profile: name=
sysadmin, server=nexus, user=sysadmin, pass=Hoatran@2024! - SSH: ✅ Install OpenSSH server
- Snaps: bỏ chọn tất cả → Reboot
1.4 Cấu hình sau cài đặt
# Ubuntu 24.04 có needrestart: đặt chế độ tự động để apt không bật hộp thoại hỏi khởi động lại dịch vụ
export NEEDRESTART_MODE=a
apt update && apt upgrade -y
apt install -y qemu-guest-agent curl wget git vim net-tools ca-certificates \
gnupg lsb-release apt-transport-https software-properties-common cron
systemctl enable --now qemu-guest-agent
hostnamectl set-hostname nexus
echo "127.0.1.1 nexus nexus.hoatranlabs.local" >> /etc/hosts
# Static IP
# Tên NIC trên VM q35 thường là ens18 hoặc enp6s18: xem tên thật trước, đừng gõ cứng
ip -br link
NIC=$(ip -br link | awk '$1!="lo"{print $1; exit}')
echo "NIC = $NIC"
# Ubuntu 24.04: installer/cloud-init ghi mạng DHCP vào /etc/netplan/50-cloud-init.yaml; nếu để nguyên,
# cấu hình đó cộng dồn với IP tĩnh bên dưới -> tắt cloud-init quản lý mạng và xóa file cũ
echo 'network: {config: disabled}' > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
rm -f /etc/netplan/50-cloud-init.yaml /etc/netplan/00-installer-config.yaml
cat > /etc/netplan/50-nexus.yaml << EOF
network:
version: 2
ethernets:
${NIC}:
addresses: [10.11.65.67/24]
routes:
- to: default
via: 10.11.65.1
nameservers:
addresses: [10.11.45.53]
search: [hoatranlabs.local]
EOF
chmod 600 /etc/netplan/50-nexus.yaml
netplan apply # đang SSH bằng IP DHCP thì phiên sẽ đứt: đăng nhập lại bằng 10.11.65.67
# Verify
ip -4 a show "$NIC" | grep "inet "
Cài đặt Nexus Repository
Cài Docker Engine · Tạo cấu trúc thư mục · Docker Compose
2.1 Cài Docker Engine
# Gỡ gói Docker xung đột của Ubuntu nếu có (không lỗi khi chưa cài)
apt remove -y $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null | cut -f1)
# Repo chính thức download.docker.com, suite noble (Ubuntu 24.04), nguồn dạng deb822 + Signed-By
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
cat > /etc/apt/sources.list.d/docker.sources << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl enable --now docker
usermod -aG docker sysadmin
2.2 Tạo cấu trúc thư mục
# Đĩa dữ liệu scsi1 (HDD vm-bulk, 100 GB) thường là /dev/sdb: kiểm bằng lsblk trước, vì mkfs xóa sạch đĩa được chọn
lsblk -f
mkfs.ext4 -m 0 -L nexus-data /dev/sdb
mkdir -p /opt/nexus/data
echo "UUID=$(blkid -s UUID -o value /dev/sdb) /opt/nexus/data ext4 defaults,noatime,nofail 0 2" >> /etc/fstab
systemctl daemon-reload && mount -a
findmnt /opt/nexus/data
chown -R 200:200 /opt/nexus/data # Nexus container chạy với UID 200 (chạy SAU khi mount)
2.3 Docker Compose
cat > /opt/nexus/docker-compose.yml << 'EOF'
version: "3.8"
services:
nexus:
# Ghim phiên bản (không dùng latest): 3.96.4 là bản Community Edition đang hỗ trợ (3.77.0+ thay cho OSS);
# endpoint metrics tích hợp ở mục 4.2 (/service/rest/metrics/prometheus) áp dụng cho 3.81 trở lên
image: sonatype/nexus3:3.96.4
container_name: nexus
restart: unless-stopped
environment:
INSTALL4J_ADD_VM_PARAMS: >-
-Xms2g -Xmx4g
-XX:MaxDirectMemorySize=2g
-Djava.util.prefs.userRoot=/nexus-data/javaprefs
volumes:
- /opt/nexus/data:/nexus-data
ports:
- "127.0.0.1:8081:8081" # Web UI / REST API
- "5000:5000" # Docker hosted registry (internal)
- "5001:5001" # Docker proxy registry (docker.io)
- "5002:5002" # Docker proxy registry (gcr.io)
- "5003:5003" # Docker proxy registry (quay.io)
- "5004:5004" # Docker proxy registry (registry.k8s.io)
ulimits:
nofile:
soft: 65536
hard: 65536
healthcheck:
test: ["CMD", "curl", "-sf", "http://localhost:8081/service/rest/v1/status"]
interval: 30s
timeout: 10s
retries: 10
start_period: 120s
EOF
cd /opt/nexus
docker compose up -d
# Theo dõi khởi động (mất 3-5 phút lần đầu)
docker compose logs -f nexus
# Chờ dòng: Started Sonatype Nexus
2.4 Lấy mật khẩu admin ban đầu
# Sau khi Nexus khởi động xong
docker exec nexus cat /nexus-data/admin.password
# Ghi lại mật khẩu này
2.5 Cài Nginx Reverse Proxy
apt install -y nginx
# Tạo cấu hình Nginx cho Nexus
cat > /etc/nginx/sites-available/nexus << 'NGINX_EOF'
# Nexus Web UI
server {
listen 80;
server_name nexus.hoatranlabs.local;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name nexus.hoatranlabs.local;
ssl_certificate /etc/ssl/certs/nexus.crt;
ssl_certificate_key /etc/ssl/private/nexus.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
client_max_body_size 2048m;
location / {
proxy_pass http://127.0.0.1:8081;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_read_timeout 600;
}
}
# Docker Internal Hosted Registry
server {
listen 443 ssl;
server_name docker-internal.hoatranlabs.local;
ssl_certificate /etc/ssl/certs/nexus.crt;
ssl_certificate_key /etc/ssl/private/nexus.key;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 2048m;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_read_timeout 600;
}
}
NGINX_EOF
ln -s /etc/nginx/sites-available/nexus /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
# Chưa chạy `nginx -t` ở bước này: vhost trên trỏ tới cert /etc/ssl/certs/nexus.crt
# và key /etc/ssl/private/nexus.key, hai file này chỉ được cấp ở mục 3.1 (step-CA).
# `nginx -t` và việc nạp vhost sẽ thực hiện ở cuối mục 3.1, sau khi đã có cert.
Cấu hình
TLS Certificate từ step-CA · Cấu hình ban đầu qua Web UI · Tạo Repositories
3.1 TLS Certificate từ step-CA
# Cài step CLI 0.31.0 (gói .deb, giá trị dùng chung của lab)
wget -O /tmp/step-cli.deb \
https://dl.smallstep.com/gh-release/cli/gh-release-header/v0.31.0/step-cli_0.31.0-1_amd64.deb
dpkg -i /tmp/step-cli.deb
step version
# Bootstrap trust
step ca bootstrap \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--fingerprint [FINGERPRINT_TU_VM242] \
--install
# Lưu Root CA ở đường dẫn dùng chung của lab (như bài 13, 21, 22) để lệnh bên dưới dùng --root
# (nếu VM đã chạy distribute-root-ca.sh ở bài 13 thì file này đã có sẵn)
step ca root /usr/local/share/ca-certificates/hoatranlabs-root.crt
update-ca-certificates
# Request certificate với SAN cho cả 2 hostname
step ca certificate nexus.hoatranlabs.local \
/etc/ssl/certs/nexus.crt \
/etc/ssl/private/nexus.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--san docker-internal.hoatranlabs.local \
--not-after 2160h
# Kiểm tra cấu hình Nginx (lúc này cert đã có) và nạp vhost nexus
# (Nginx đã được apt khởi động ở mục 2.5 với cấu hình mặc định nên cần restart)
nginx -t && systemctl enable nginx && systemctl restart nginx
# Auto-renew
cat > /usr/local/bin/renew-nexus-cert.sh << 'EOF'
#!/bin/bash
step ca renew --force \
/etc/ssl/certs/nexus.crt \
/etc/ssl/private/nexus.key
nginx -s reload
EOF
chmod +x /usr/local/bin/renew-nexus-cert.sh
echo "0 3 * * 0 root /usr/local/bin/renew-nexus-cert.sh >> /var/log/cert-renew.log 2>&1" \
> /etc/cron.d/nexus-cert-renew
3.2 Cấu hình ban đầu qua Web UI
Hoatran@2024!- Anonymous access: Disable (yêu cầu authentication); chấp nhận EULA của Community Edition khi wizard hỏi (bắt buộc: chưa chấp nhận thì không tải lên/xuống component được; nếu bỏ qua wizard thì chấp nhận qua API
POST /service/rest/v1/system/eula, gửiaccepted: truekèm đúng nguyên văndisclaimerlấy từGETcùng endpoint)
Outreach Management = OFF (tắt telemetry)https://nexus.hoatranlabs.localDocker Bearer Token Realm sang danh sách Active → Save. Realm này bắt buộc để Docker client và containerd đăng nhập/pull được các repo Docker ở mục 3.3 (nhất là khi đã tắt anonymous ở bước 3)
3.3 Tạo Repositories
Dùng Nexus REST API để tạo tất cả repos. Chạy script sau sau khi admin password đã đổi:
NEXUS="https://nexus.hoatranlabs.local"
AUTH="admin:Hoatran@2024!"
# ——— Docker Hosted (internal images) ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/docker/hosted" \
-H "Content-Type: application/json" -d '{
"name": "docker-internal",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true, "writePolicy": "allow"},
"docker": {"v1Enabled": true, "forceBasicAuth": false, "httpPort": 5000}
}'
# ——— Docker Proxy: docker.io ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/docker/proxy" \
-H "Content-Type: application/json" -d '{
"name": "docker-proxy-dockerhub",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://registry-1.docker.io", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"docker": {"v1Enabled": true, "forceBasicAuth": false, "httpPort": 5001},
"dockerProxy": {"indexType": "HUB", "indexUrl": "https://index.docker.io"}
}'
# ——— Docker Proxy: gcr.io + quay.io + registry.k8s.io (mỗi repo một cổng riêng: 5002 / 5003 / 5004) ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/docker/proxy" \
-H "Content-Type: application/json" -d '{
"name": "docker-proxy-gcr",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://gcr.io", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"docker": {"v1Enabled": false, "forceBasicAuth": false, "httpPort": 5002},
"dockerProxy": {"indexType": "REGISTRY"}
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/docker/proxy" \
-H "Content-Type: application/json" -d '{
"name": "docker-proxy-quay",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://quay.io", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"docker": {"v1Enabled": false, "forceBasicAuth": false, "httpPort": 5003},
"dockerProxy": {"indexType": "REGISTRY"}
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/docker/proxy" \
-H "Content-Type: application/json" -d '{
"name": "docker-proxy-k8s",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://registry.k8s.io", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"docker": {"v1Enabled": false, "forceBasicAuth": false, "httpPort": 5004},
"dockerProxy": {"indexType": "REGISTRY"}
}'
# ——— npm proxy + hosted ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/npm/proxy" \
-H "Content-Type: application/json" -d '{
"name": "npm-proxy",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://registry.npmjs.org", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true}
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/npm/hosted" \
-H "Content-Type: application/json" -d '{
"name": "npm-internal",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true, "writePolicy": "allow_once"}
}'
# ——— Maven proxy + hosted ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/maven/proxy" \
-H "Content-Type: application/json" -d '{
"name": "maven-proxy-central",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://repo1.maven.org/maven2/", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"maven": {"versionPolicy": "MIXED", "layoutPolicy": "STRICT"}
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/maven/hosted" \
-H "Content-Type: application/json" -d '{
"name": "maven-internal",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true, "writePolicy": "allow_once"},
"maven": {"versionPolicy": "MIXED", "layoutPolicy": "STRICT"}
}'
# ——— PyPI proxy + hosted ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/pypi/proxy" \
-H "Content-Type: application/json" -d '{
"name": "pypi-proxy",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "https://pypi.org", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true}
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/pypi/hosted" \
-H "Content-Type: application/json" -d '{
"name": "pypi-internal",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true, "writePolicy": "allow_once"}
}'
# ——— apt proxy (Ubuntu 24.04 noble) ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/repositories/apt/proxy" \
-H "Content-Type: application/json" -d '{
"name": "apt-ubuntu-proxy",
"online": true,
"storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
"proxy": {"remoteUrl": "http://archive.ubuntu.com/ubuntu/", "contentMaxAge": 1440, "metadataMaxAge": 1440},
"negativeCache": {"enabled": true, "timeToLive": 1440},
"httpClient": {"blocked": false, "autoBlock": true},
"apt": {"distribution": "noble", "flat": false}
}'
# ——— Role + user cho Prometheus (endpoint metrics tích hợp cần quyền nx-metrics-all; anonymous đã tắt ở mục 3.2) ———
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/security/roles" \
-H "Content-Type: application/json" -d '{
"id": "nx-metrics",
"name": "nx-metrics",
"description": "Prometheus scrape /service/rest/metrics/prometheus",
"privileges": ["nx-metrics-all"],
"roles": []
}'
curl -su "$AUTH" -X POST "$NEXUS/service/rest/v1/security/users" \
-H "Content-Type: application/json" -d '{
"userId": "prometheus",
"firstName": "Prometheus",
"lastName": "Scraper",
"emailAddress": "[email protected]",
"password": "Prometheus@Nexus2024!",
"status": "active",
"roles": ["nx-metrics"]
}'
echo "=== Repositories created ==="
curl -su "$AUTH" "$NEXUS/service/rest/v1/repositories" | python3 -c \
"import sys,json; [print(r['name'], r['type'], r['format']) for r in json.load(sys.stdin)]"
Tạo Cleanup Policy để các repo proxy không làm đầy đĩa (script trên chưa tạo policy; làm qua Web UI):
- Administration → Repository → Cleanup Policies → Create Cleanup Policy: Name
cleanup-proxy-14d, FormatAll formats, tiêu chí Component Usage (xóa component không được tải trong 14 ngày; lab dùng 14 ngày thay cho 30 ngày vì đĩa dữ liệu chỉ 100 GB) → Save. - Administration → Repository → Repositories → mở từng repo proxy (
docker-proxy-dockerhub,docker-proxy-gcr,docker-proxy-quay,docker-proxy-k8s,npm-proxy,maven-proxy-central,pypi-proxy,apt-ubuntu-proxy) → mục Cleanup: chuyển policy từ Available sang Applied → Save. - Administration → System → Tasks: task
Admin - Cleanup repositories using their associated policies(mặc định chạy mỗi giờ) chỉ xóa mềm component. Tạo thêm taskAdmin - Compact blob store(blob storedefault, lịch hằng tuần) để dung lượng đĩa thực sự được giải phóng.
3.4 Authentik LDAP (đăng nhập bằng tài khoản Authentik)
# Đăng nhập bằng tài khoản Authentik qua LDAP outpost đã tạo ở bài 14, mục 9.1
# (Provider legacy-ldap, ldap://10.11.25.40:389, Base DN DC=hoatranlabs,DC=local).
# Nexus Community Edition có LDAP; SAML chỉ có ở bản Pro nên bài không dùng SAML.
# Nếu không cần đăng nhập bằng tài khoản Authentik, bỏ qua mục này và dùng tài khoản local của Nexus (Administration → Security → Users).
# BƯỚC 1: Trên Authentik
# Tạo group nexus-admins và nexus-devs, thêm user vào group.
# Tài khoản dịch vụ ldapservice (dùng ở bài 14, mục 14.4) cần quyền "Search full LDAP directory"
# trên provider legacy-ldap để Nexus tra cứu được user và group.
# Lưu ý MFA: bài 14 (mục 10) gắn TOTP vào default-authentication-flow, cũng là Bind Flow của legacy-ldap. Tài khoản
# ldapservice (Bind DN lưu cố định trong Nexus) phải là tài khoản KHÔNG bật MFA và không thuộc nhóm bị bắt MFA
# (authentik Admins), vì mã TOTP đổi liên tục, không lưu được trong cấu hình Nexus. User thật bật MFA chỉ đăng nhập Nexus
# được khi provider bật "Code-based MFA Support" và nhập mật khẩu dạng matkhau;123456 (mã TOTP sau dấu ;);
# hoặc cho provider một Bind Flow riêng không có stage MFA.
# FortiGate: cho phép 10.11.65.67 -> 10.11.25.40 cổng 389/tcp (Nexus ở VLAN 65, Authentik ở VLAN 25).
# Lưu ý: ldap:// cổng 389 không mã hóa (mật khẩu bind và mật khẩu user đi dạng rõ), chỉ dùng trong mạng nội bộ của lab.
# LDAPS (tùy chọn): trên provider legacy-ldap đặt Certificate + TLS Server Name (cert từ step-CA) để outpost nhận kết nối
# cổng 636; trong Nexus chọn Protocol ldaps, Port 636, thêm cert vào Security → SSL Certificates rồi tick
# "Use certificates stored in the Nexus Repository truststore"; FortiGate mở thêm 636/tcp.
# BƯỚC 2: Trên Nexus — bật realm
# Administration → Security → Realms: chuyển "LDAP Realm" sang Active, đặt dưới
# "Local Authenticating Realm" → Save
# BƯỚC 3: Administration → Security → LDAP → Create connection
# Name: authentik
# Protocol: ldap | Hostname: 10.11.25.40 | Port: 389
# Search base DN: DC=hoatranlabs,DC=local
# Authentication method: Simple Authentication
# Username or DN: cn=ldapservice,ou=users,DC=hoatranlabs,DC=local
# Password: <PASSWORD>
# Bước User and Group Mapping: chọn Configuration template "Generic Ldap Server" rồi sửa:
# User relative DN: ou=users | User subtree: ON | Object class: user
# User ID attribute: cn | Real name attribute: name | Email attribute: mail
# Map LDAP groups as roles: ON | Group type: Static Groups
# Group relative DN: ou=groups | Group subtree: ON | Group object class: group
# Group ID attribute: cn | Group member attribute: member | Group member format: ${dn}
# Bấm "Verify user mapping" và "Verify login" (bằng một tài khoản Authentik thật) để kiểm tra → Create
# BƯỚC 4: Role mapping
# Administration → Security → Roles → Create role → Type: External Role Mapping → LDAP
# Mapped role: nexus-admins → gán role nx-admin
# Mapped role: nexus-devs → Role Name: nx-developer, Privileges:
# nx-repository-view-*-*-browse, nx-repository-view-*-*-read,
# nx-repository-view-*-*-add, nx-repository-view-*-*-edit
3.5 Cấu hình K3s dùng Nexus làm Registry Mirror
# Chạy trên TẤT CẢ K3s nodes (xem bài 28)
#
# K3s chỉ đọc MỘT file /etc/rancher/k3s/registries.yaml. File này đã được tạo ở bài 29
# (mục 4.3) với mirror + auth cho harbor.hoatranlabs.local -> GỘP các mục Nexus vào file đó,
# KHÔNG ghi đè làm mất mục Harbor. Sao lưu trước rồi ghi lại file ở dạng đã gộp:
cp /etc/rancher/k3s/registries.yaml /etc/rancher/k3s/registries.yaml.bak
cat > /etc/rancher/k3s/registries.yaml << 'EOF'
mirrors:
# --- Harbor: giữ nguyên từ bài 29 ---
"harbor.hoatranlabs.local":
endpoint:
- "https://harbor.hoatranlabs.local"
# --- Nexus: thêm mới ở bài 31 (cổng 5001-5004 khớp httpPort ở mục 3.3) ---
"docker.io":
endpoint:
- "http://10.11.65.67:5001"
"gcr.io":
endpoint:
- "http://10.11.65.67:5002"
"quay.io":
endpoint:
- "http://10.11.65.67:5003"
"registry.k8s.io":
endpoint:
- "http://10.11.65.67:5004"
"docker-internal.hoatranlabs.local":
endpoint:
- "https://docker-internal.hoatranlabs.local"
configs:
# --- Harbor: giữ nguyên từ bài 29 ---
"harbor.hoatranlabs.local":
auth:
username: admin
password: "Admin@Harbor2024!"
tls:
ca_file: /usr/local/share/ca-certificates/hoatranlabs-root.crt
# --- Nexus: thêm mới ở bài 31 ---
"docker-internal.hoatranlabs.local":
auth:
username: admin
password: "Hoatran@2024!"
tls:
ca_file: /usr/local/share/ca-certificates/hoatranlabs-root.crt
# Anonymous đã tắt ở mục 3.2 nên các mirror proxy (endpoint http://10.11.65.67:5001-5004) cũng phải có auth;
# key của configs là host:port của endpoint, endpoint http không cần khối tls
"10.11.65.67:5001":
auth:
username: admin
password: "Hoatran@2024!"
"10.11.65.67:5002":
auth:
username: admin
password: "Hoatran@2024!"
"10.11.65.67:5003":
auth:
username: admin
password: "Hoatran@2024!"
"10.11.65.67:5004":
auth:
username: admin
password: "Hoatran@2024!"
EOF
# Restart K3s/K3s-agent để apply
# Control plane nodes:
systemctl restart k3s
# Worker nodes:
systemctl restart k3s-agent
Tích hợp với hạ tầng
Pi-hole DNS · Prometheus Monitoring · Gitea CI — Sử dụng Nexus proxy
4.1 Pi-hole DNS
# Record nexus.hoatranlabs.local đã có trong bảng VLAN_SRV / script add_dns_records.sh của bài 12;
# docker-internal.hoatranlabs.local (alias của nexus) thì thêm thủ công.
# Pi-hole Admin (http://10.11.45.53/admin) → Settings → Local DNS Records:
nexus.hoatranlabs.local → 10.11.65.67
docker-internal.hoatranlabs.local → 10.11.65.67
4.2 Prometheus Monitoring
# SSH vào VM235 (Prometheus): ssh [email protected]
# Thêm job vào cuối file (mục scrape_configs là mục cuối của prometheus.yml ở bài 15)
# Scrape endpoint Prometheus tích hợp của Nexus qua Nginx HTTPS (không còn exporter cổng 9184):
# - Nexus 3.81 trở lên: /service/rest/metrics/prometheus (trước 3.81 là /service/metrics/prometheus); cần quyền nx-metrics-all
# nên dùng user prometheus (role nx-metrics) đã tạo ở mục 3.3, xác thực Basic
# - ca_file là đường dẫn TRONG container Prometheus: compose bài 15 đã mount root CA của host vào /etc/prometheus/certs/hoatranlabs-root.crt
# - FortiGate: mở 10.11.45.35 -> 10.11.65.67 cổng 443/tcp (thay rule 9184/tcp của exporter cũ; hàng tương ứng ở bảng rule của bài 15)
cat >> /opt/prometheus/prometheus.yml << 'EOF'
- job_name: 'nexus'
metrics_path: /service/rest/metrics/prometheus
scheme: https
basic_auth:
username: prometheus
password: 'Prometheus@Nexus2024!'
tls_config:
ca_file: /etc/prometheus/certs/hoatranlabs-root.crt
static_configs:
- targets: ['nexus.hoatranlabs.local:443']
EOF
curl -X POST http://10.11.45.35:9090/-/reload
4.3 Gitea CI — Sử dụng Nexus proxy
Thêm vào .gitea/workflows/*.yaml để CI dùng Nexus thay vì trực tiếp internet:
# Cho npm
env:
NPM_CONFIG_REGISTRY: https://nexus.hoatranlabs.local/repository/npm-proxy/
# Cho pip
env:
PIP_INDEX_URL: https://nexus.hoatranlabs.local/repository/pypi-proxy/simple/
# Cho Maven (settings.xml)
# <mirror><id>nexus</id><url>https://nexus.hoatranlabs.local/repository/maven-proxy-central/</url></mirror>
4.4 PBS Backup
# Cài proxmox-backup-client (bản liên kết tĩnh) từ repository client-only công khai của Proxmox.
# Suite trixie của repo pbs-client có gói proxmox-backup-client-static (chỉ phụ thuộc qrencode), không phụ thuộc
# glibc của Ubuntu 24.04; lệnh sử dụng vẫn là proxmox-backup-client. Nguồn dạng deb822 + Signed-By (không dùng apt-key).
# Chạy trên Ubuntu 24.04 (noble): cần kiểm lại trên máy thật.
wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
-O /usr/share/keyrings/proxmox-archive-keyring.gpg
cat > /etc/apt/sources.list.d/pbs-client.sources << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
apt update && apt install -y proxmox-backup-client-static
# Script backup
cat > /usr/local/bin/nexus-backup.sh << 'EOF'
#!/bin/bash
set -e
cd /opt/nexus
docker compose stop nexus
# Backup file-level từ trong VM: API token vm-backup@pbs!nexus + namespace vm-nexus
# (tạo theo bài 04, mục 5.7); PBS_PASSWORD là secret của token đó
export PBS_PASSWORD="<TOKEN_SECRET>"
proxmox-backup-client backup \
"nexus-data.pxar:/opt/nexus/data" \
--repository "vm-backup@[email protected]:syno-primary" \
--ns vm-nexus
docker compose start nexus
EOF
chmod +x /usr/local/bin/nexus-backup.sh
echo "0 2 * * 6 root /usr/local/bin/nexus-backup.sh >> /var/log/nexus-backup.log 2>&1" \
> /etc/cron.d/nexus-backup
Kiểm tra & Xác minh
# 1. Nexus container healthy
cd /opt/nexus
docker compose ps
# Expected: nexus (healthy)
# 2. API health check
curl -su admin:Hoatran@2024! \
https://nexus.hoatranlabs.local/service/rest/v1/status
# Expected: HTTP 200
# 3. Danh sách repositories
curl -su admin:Hoatran@2024! \
"https://nexus.hoatranlabs.local/service/rest/v1/repositories" \
| python3 -c "import sys,json; [print(r['name']) for r in json.load(sys.stdin)]"
# Expected: docker-internal, docker-proxy-dockerhub, npm-proxy, npm-internal, ...
# 4. Test Docker proxy pull qua Nexus (chạy trên VM nexus; anonymous đã tắt nên phải docker login trước.
# Dùng localhost vì Docker chỉ cho phép registry HTTP ở loopback, còn 10.11.65.67:5001 sẽ bị đòi HTTPS)
docker login localhost:5001 -u admin -p "Hoatran@2024!"
docker pull localhost:5001/library/alpine:latest
# Expected: pull thành công
# 5. Test push image lên docker-internal
docker tag alpine:latest docker-internal.hoatranlabs.local/test/alpine:latest
docker login docker-internal.hoatranlabs.local -u admin -p "Hoatran@2024!"
docker push docker-internal.hoatranlabs.local/test/alpine:latest
# Expected: push thành công
# 6. Test npm proxy
npm install --registry https://nexus.hoatranlabs.local/repository/npm-proxy/ lodash
# Expected: install thành công
# 7. Kiểm tra endpoint metrics tích hợp (Prometheus: Status → Targets, job nexus phải UP)
curl -su 'prometheus:Prometheus@Nexus2024!' \
https://nexus.hoatranlabs.local/service/rest/metrics/prometheus | head -20
# Expected: HTTP 200 và các dòng metrics định dạng Prometheus (anonymous đã tắt nên không có user thì báo 401)
# 8. Test K3s dùng Nexus mirror
# Pull image trên K3s node — sẽ đi qua Nexus
kubectl run test-pull --image=nginx:alpine --restart=Never
kubectl get pod test-pull
kubectl delete pod test-pull
Troubleshooting
| Vấn đề | Nguyên nhân | Giải pháp |
|---|---|---|
| Nexus không start | Heap quá nhỏ hoặc ulimits | Kiểm tra docker logs nexus — tăng -Xmx trong INSTALL4J_ADD_VM_PARAMS |
| Docker pull qua proxy fail | Port 5001 chưa mở | Kiểm tra docker ps — cổng 5001 bind đúng chưa; kiểm tra firewall |
| K3s vẫn pull từ Docker Hub | registries.yaml chưa reload | systemctl restart k3s / k3s-agent; kiểm tra /etc/rancher/k3s/registries.yaml |
| npm install fail qua proxy | Registry URL sai hoặc SSL cert | Thêm npm config set cafile /usr/local/share/ca-certificates/hoatranlabs-root.crt |
| Disk đầy nhanh | Blob store không có cleanup policy | Administration → Repository → Blob Stores → xem dung lượng; tạo Cleanup Policy |
| Đăng nhập bằng tài khoản Authentik (LDAP) thất bại | LDAP Realm chưa Active, sai Search base/Bind DN hoặc FortiGate chặn 389/tcp từ 10.11.65.67 tới 10.11.25.40 | Dùng "Verify user mapping" / "Verify login" trong Security → LDAP; kiểm tra rule FortiGate và LDAP outpost (bài 14, mục 9.1) |
docker login/pull báo 401 Unauthorized | Docker Bearer Token Realm chưa Active, hoặc registries.yaml thiếu auth cho mirror (anonymous đã tắt) | Bật realm ở mục 3.2 bước 6; kiểm tra khối configs trong /etc/rancher/k3s/registries.yaml rồi restart K3s |
| Pull/push component bị từ chối dù đăng nhập đúng | Chưa chấp nhận EULA Community Edition, hoặc vượt giới hạn 40.000 component / 100.000 request mỗi ngày | Chấp nhận EULA (mục 3.2); xem Usage Center trên trang chủ Nexus, dọn component bằng Cleanup Policy (mục 3.3) |
Prometheus target nexus báo 401/403/404 | User prometheus thiếu role nx-metrics (privilege nx-metrics-all) hoặc sai mật khẩu; Nexus trước 3.81 dùng đường dẫn cũ /service/metrics/prometheus | Kiểm tra user/role ở mục 3.3 và lệnh curl ở mục 5 #7; đường dẫn /service/rest/metrics/prometheus cho 3.81 trở lên |
client_max_body_size lỗi | Nginx giới hạn upload | Tăng client_max_body_size trong nginx config và reload |
Checklist triển khai
- VM 267 tạo thành công, qemu-agent chạy
- Ubuntu Server 24.04.5 LTS cài đặt, update, static IP 10.11.65.67 hoạt động (không còn
50-cloud-init.yamlDHCP) - Docker Engine và Docker Compose Plugin cài thành công từ repo
download.docker.comsuitenoble - Container nexus healthy (kiểm tra
docker compose ps) - TLS certificate từ step-CA với SAN nexus + docker-internal
- Nginx cài và cấu hình cho cả 2 hostname
- DNS records (nexus + docker-internal) trong Pi-hole
- Web UI accessible: https://nexus.hoatranlabs.local
- Admin password đã đổi, anonymous access disabled, EULA Community Edition đã chấp nhận, Docker Bearer Token Realm đã Active
- Tất cả repositories tạo thành công (10+ repos)
- Docker push/pull qua docker-internal.hoatranlabs.local hoạt động
- Docker proxy pull qua port 5001 hoạt động
- K3s registries.yaml (đã gộp với mục Harbor từ bài 29) cấu hình trên tất cả 6 K3s nodes, restarted
- Đăng nhập bằng tài khoản Authentik qua LDAP (mục 3.4) hoạt động, hoặc dùng tài khoản local nếu bỏ qua mục 3.4
- Prometheus scrape endpoint metrics tích hợp
/service/rest/metrics/prometheushoạt động (user prometheus, không còn exporter) - Prometheus job thêm vào VM235
- Gitea CI runners cấu hình dùng Nexus proxy
- PBS backup lần đầu thành công
- Cleanup Policy (mục 3.3) tạo và gán cho các repo proxy, có task Compact blob store để tránh disk đầy