Administrator/NANOKVM-sipeed_wiki-MIRROR
1
0
Fork 0
mirror of https://github.com/sipeed/sipeed_wiki.git synced 2026-09-11 00:22:49 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #792 from 916BGAI/main

Browse Source 
first commit NanoCluster document
This commit is contained in:
Caize Wu
2025-04-14 15:19:33 +08:00
committed by GitHub
parent ba7860bad0 dd43321163
commit 5d94e51a8b
38 changed files with 1616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/hardware/en/cluster/NanoCluster/distcc.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: distcc Deployment
---
## Introduction
[distcc](https://github.com/distcc/distcc) is a distributed C/C++ compilation system that speeds up the compilation process by distributing compilation tasks across multiple machines. It allows you to leverage the computing power of multiple computers to compile code faster, making it especially useful for large codebases or resource-constrained environments.
## Deployment Guide
### Server
For Debian-based systems, you can install distcc directly using the package manager:
```bash
sudo apt install distcc
```
Start the distcc service:
```bash
distccd --daemon --allow 192.168.0.0/24 # Allow specific IP range to access
```
### Client
```bash
sudo apt install distcc distcc-pump
```
Set up the DISTCC_HOSTS environment variable to specify the available worker nodes. You can add the following to your .bashrc
```bash
export DISTCC_POTENTIAL_HOSTS='localhost 192.168.0.240 192.168.0.243 192.168.0.245 192.168.0.246'
```
Then, you can try compiling a simple program to check if distcc is correctly distributing the compilation tasks:
```bash
distcc-pump distcc -o test test.c
```
```bash
sipeed@lpi3h-a2d1:~/distcc$ distcc-pump distcc -o test test.c
__________Using distcc-pump from /usr/bin
__________Found 4 available distcc servers
__________Shutting down distcc-pump include server
```
## Compilation Testing
To test whether distcc effectively accelerates the compilation process, we used OpenSSL for the compilation test. OpenSSL is a widely-used C library with a large codebase, making it a good candidate to test the effectiveness of distributed compilation.
```bash
git clone https://github.com/openssl/openssl.git
cd openssl
./config
distcc-pump make -j20 CC=distcc
```
You can use distccmon-text to check the current distribution of compilation tasks:
```bash
sipeed@lpi3h-2193:~$ distccmon-text
67535 Compile cmp_ctx.c 192.168.0.240[0]
67528 Compile cmp_asn.c 192.168.0.240[1]
67635 Compile cms_dh.c 192.168.0.240[2]
67569 Compile cmp_http.c 192.168.0.243[0]
67696 Compile cms_io.c 192.168.0.245[0]
67583 Compile cmp_server.c 192.168.0.245[1]
67561 Compile cmp_hdr.c 192.168.0.245[2]
67606 Compile cmp_vfy.c 192.168.0.245[3]
67657 Compile cms_enc.c 192.168.0.246[1]
67672 Compile cms_env.c 192.168.0.246[2]
```
### Compilation Performance Comparison
In the testing process, we compiled the OpenSSL project using both single-machine compilation and distributed compilation (5 machines). Below are the results for each method:
##### Single-Machine Compilation (without distcc)
```bash
real 18m11.760s
user 64m37.024s
sys 5m56.326s
```
##### Distributed Compilation (using distcc)
```bash
real 6m32.262s
user 18m39.468s
sys 4m30.008s
```
As seen, the compilation time using distcc for distributed compilation is significantly reduced, from 18 minutes to about 6 minutes. The acceleration effect of distributed compilation is evident, and it also helps alleviate the load on individual machines.

190
docs/hardware/en/cluster/NanoCluster/index.md Normal file
View File

@@ -0,0 +1,190 @@
---
title: Introduction
---
## Introduction
NanoCluster is an ultra-miniature cluster board developed by Sipeed, featuring 7 SOM slots interconnected via a RISC-V-based Gigabit switch. It supports USB-C PD power supply and optional PoE expansion. Additionally, NanoCluster provides independent UART and power control, making it an ideal entry-level platform for HomeLab users exploring distributed computing, Kubernetes, Docker, and edge computing.
NanoCluster is compatible with Sipeed's Longan Module 3H (4 × Cortex-A53), M4N (4 × Cortex-A55 + NPU), as well as the Raspberry Pi Compute Module 4 (4 × Cortex-A72) and Compute Module 5 (4× Cortex-A76). Users can freely choose compute modules based on performance needs and budget, or mix and match different architectures to build a highly customized and heterogeneous computing cluster.
The NanoCluster adopts an open SOM interface standard, supporting both official core modules and custom adapter boards for third-party SOM solutions. This design greatly enhances the platform's flexibility.
<br>
![产品特写图](../../../zh/cluster/NanoCluster/assets/product.png)
## Technical Specifications
### Baseboard
<table>
<thead>
<tr>
<th colspan="2">Hardware Specifications</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>SOM Slots</strong></td>
<td>7× Dual M.2 M-Key vertical slots</td>
</tr>
<tr>
<td><strong>Power Supply</strong></td>
<td>USB-C 20V PD (Max 60W), Optional 60W PoE module</td>
</tr>
<tr>
<td><strong>Ethernet</strong></td>
<td>Integrated RISC-V Gigabit switch chip JL6108 for high-speed interconnection, supporting web-based management and SDK-based custom feature development</td>
</tr>
<tr>
<td><strong>USB Ports</strong></td>
<td>USB-A Host (Top), USB-A OTG (Bottom), connected to Slot 1</td>
</tr>
<tr>
<td><strong>Display Interface</strong></td>
<td>HDMI, connected to Slot 1</td>
</tr>
<tr>
<td><strong>Cooling System</strong></td>
<td>Equipped with a 60mm 2-pin fan for efficient cooling</td>
</tr>
<tr>
<td><strong>Status Indicators</strong></td>
<td>7× SYS LED indicators for node status monitoring</td>
</tr>
<tr>
<td><strong>Serial Communication</strong></td>
<td>7× independent UARTs for easy debugging and control, optional quad-serial USB module available</td>
</tr>
<tr>
<td><strong>Power Management</strong></td>
<td>Slot1 centrally manages other Slots and switch power through IO expansion chip</td>
</tr>
<tr>
<td><strong>Power Consumption</strong></td>
<td>3.6 W</td>
</tr>
<tr>
<td><strong>Dimensions</strong></td>
<td>PCBA: 88x57mm, approximately 100x60x60mm with SOMs installed and fan mounted</td>
</tr>
</tbody>
</table>
![底板裸板特写图](../../../zh/cluster/NanoCluster/assets/bare_board.jpeg)
### SOM
<table>
<tr>
<th>SOM</th>
<th>LM3H</th>
<th>M4N</th>
<th>CM4</th>
<th>CM5</th>
</tr>
<tr>
<td>SoC</td>
<td>H618</td>
<td>AX650N</td>
<td>BCM2711</td>
<td>BCM2712</td>
</tr>
<tr>
<td>Memory</td>
<td>2GB ~ 4GB</td>
<td>8GB</td>
<td>1GB ~ 8GB</td>
<td>1GB ~ 16GB</td>
</tr>
<tr>
<td>eMMC</td>
<td>32GB</td>
<td>32GB</td>
<td>0GB ~ 64GB</td>
<td>0GB ~ 64GB</td>
</tr>
<tr>
<td>CPU</td>
<td>4 × A53<br>1.5 GHz</td>
<td>8 × A55<br>1.6 GHz</td>
<td>4 × A72<br>1.5 GHz</td>
<td>4 × A76<br>2.4 GHz</td>
</tr>
<tr>
<td>GPU</td>
<td>Mali-G31</td>
<td>-</td>
<td>VideoCore VI</td>
<td>VideoCore VII</td>
</tr>
<tr>
<td>NPU</td>
<td>-</td>
<td>18TOPS INT8</td>
<td>-</td>
<td>-</td>
</tr>
<tr>
<td>Network</td>
<td>100M</td>
<td>1G</td>
<td>1G</td>
<td>1G</td>
</tr>
<tr>
<td>Additional Interfaces</td>
<td>None</td>
<td>Download interface + M.2 SSD + USB 3.0</td>
<td>Download interface + M.2 SSD</td>
<td>Download interface + M.2 SSD + USB 3.0</td>
</tr>
<tr>
<td>Power<br>Idle /<br>Full Load /<br>Peak</td>
<td><nobr>1.2W/2.6W/3.7W</nobr></td>
<td><nobr>3W/8.3W/9W</nobr></td>
<td><nobr>3W/4.5W/4.6W</nobr></td>
<td><nobr>4W/7.6W/8W</nobr></td>
</tr>
</table>
![SOM图](../../../zh/cluster/NanoCluster/assets/som.jpeg)
## Interface Diagram
![接口图示](../../../zh/cluster/NanoCluster/assets/board_io.jpeg)
## Hardware & Software Resources
### Baseboard Hardware
[Click to view](https://dl.sipeed.com/Cluster/NanoCluster)
### Longan Module 3H Documentation
Hardware documentation can be accessed here: [Click to view](https://dl.sipeed.com/shareURL/LONGAN/LonganPi3H). For system building and software development guides, please refer to: [Click here](https://wiki.sipeed.com/hardware/en/longan/h618/lpi3h/7_develop_mainline.html).
### M4N Documentation
[Hardware Documentation](https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock)
[Software Development Guide](https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock)
[Software Development SDK](https://github.com/AXERA-TECH/ax650n_bsp_sdk)
### Raspberry Pi Compute Module 4
[Click to view](https://www.raspberrypi.com/products/compute-module-4)
### Raspberry Pi Compute Module 5
[Click to view](https://www.raspberrypi.com/products/compute-module-5)
## Purchase Information
[Pre-order Portal](https://sipeed.com/nanocluster)
## Feedback & Support
If you have any questions or suggestions during use, please provide feedback through the following channels:
+ [Github issues](https://github.com/sipeed/NanoCluster)

116
docs/hardware/en/cluster/NanoCluster/k3s.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: K3s Deployment
---
## Introduction
[K3s](https://k3s.io/) is a lightweight version of Kubernetes. It is easy to install and requires only half the memory of Kubernetes, making it suitable for resource-constrained environments, especially for use cases like edge computing, IoT, and others.
## Deployment Guide
### Prepare the Environment
First, ensure that the network of the cluster is working correctly and that it can access the internet. You can SSH into each machine in the cluster to execute the subsequent installation commands. Make sure that the IP addresses of the master node and worker nodes are fixed, and that they can access each other over the network.
### Install K3s (Master Node)
The installation of K3s is very simple. Just run the following command on the master node:
``` bash
curl -sfL https://get.k3s.io | sh -
```
If the download is slow, you can speed up the installation by using the following command:
``` bash
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -
```
This command will automatically download and install K3s. After the installation is complete, check if the K3s service is running with the following command:
``` bash
sudo systemctl status k3s
```
If it shows `active (running)`, K3s has started successfully.
```bash
sudo systemctl status k3s
● k3s.service - Lightweight Kubernetes
Loaded: loaded (/etc/systemd/system/k3s.service; enabled; preset: enabled)
Active: active (running) since Mon 2025-02-17 12:07:15 CST; 3h 38min ago
Docs: https://k3s.io
Process: 8803 ExecStartPre=/bin/sh -xc ! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null (code=exited, status=0/SUCCESS)
Process: 8805 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
Process: 8808 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
Main PID: 8810 (k3s-server)
Tasks: 32
Memory: 583.2M
CPU: 29min 49.755s
CGroup: /system.slice/k3s.service
├─8810 "/usr/local/bin/k3s server"
└─8895 "containerd "
```
### Install K3s (Worker Nodes)
When installing K3s on the worker nodes, you need to connect them to the master node. Run the following command on the worker node to install K3s:
``` bash
curl -sfL https://get.k3s.io | K3S_URL=https://<MasterNodeIP>:6443 K3S_TOKEN=<MasterNodeToken> sh -
```
In the command above, replace `主节点IP` with the master node's IP address, and `MasterNodeIP` with the token obtained from the master node. You can retrieve the token by running the following command on the master node:
```bash
sudo cat /var/lib/rancher/k3s/server/node-token
```
After installation is complete, verify that the worker node has successfully joined the cluster by running:
```bash
sudo kubectl get nodes
```
If the worker node appears in the list with a status of `Ready`, it means the worker node has successfully joined the cluster.
```bash
sipeed@lpi3h-a2d1:~$ sudo kubectl get nodes
NAME STATUS ROLES AGE VERSION
lpi3h-1967 Ready <none> 20h v1.31.5+k3s1
lpi3h-231e Ready <none> 20h v1.31.5+k3s1
lpi3h-4782 Ready <none> 56m v1.31.5+k3s1
lpi3h-a2d1 Ready control-plane,master 23h v1.31.5+k3s1
lpi3h-ba13 Ready <none> 19h v1.31.5+k3s1
lpi3h-c06b Ready <none> 21h v1.31.5+k3s1
```
### Deploy an Application
We will create a configuration file to run a K3s container.
```bash
nano hello-kubernetes.yaml
```
The file content is as follows:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-kubernetes
spec:
replicas: 1
selector:
matchLabels:
app: hello-kubernetes
template:
metadata:
labels:
app: hello-kubernetes
spec:
containers:
- name: hello-kubernetes
image: paulbouwer/hello-kubernetes:1.10.1
env:
- name: MESSAGE
value: "Hello Kubernetes"
```
Then, use this configuration file to start a container:
```bash
sudo kubectl apply -f hello-kubernetes.yaml
```
Check the status of the pods:
```bash
sudo kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
hello-kubernetes-7fbb7f4899-zqs5x 1/1 Running 0 2m39s 10.42.0.114 arch <none> <none>
```
Finally, access the application via a browser at 10.42.0.114:8080
![hello_k3s](../../../zh/cluster/NanoCluster/assets/hello_k3s.jpeg)

404
docs/hardware/en/cluster/NanoCluster/use.md Normal file
View File

@@ -0,0 +1,404 @@
---
title: Quick Start
---
## Hardware Installation
### LM3H Installation
First, attach the heatsink to the main control chip to improve heat dissipation. When installing the core board, ensure the correct orientation to avoid damaging the device.
![mount1](../../../zh/cluster/NanoCluster/assets/mount1.jpeg)
Align the notch on the gold fingers of the core board with the slot on the mainboard. Gently place it in position and press down evenly until you hear a "click" sound, confirming that the core board is securely inserted without tilting or loosening.
![mount2](../../../zh/cluster/NanoCluster/assets/mount2.jpeg)
To remove the core board, hold both sides of the board evenly with both hands and gently pull upward. Avoid applying excessive force to one side, as this may cause damage. If the core board is tightly fitted, slightly wiggle it left and right before pulling it out. Do not pull it out forcefully to prevent damage to the gold fingers or the mainboard slot.
### CM4 and CM5 Installation
- First, install the CM4 / CM5 module onto the adapter board
![cm4_mount1](../../../zh/cluster/NanoCluster/assets/cm4_mount1.jpeg)
- Then insert the adapter board into the mainboard slot
![cm4_mount2](../../../zh/cluster/NanoCluster/assets/cm4_mount2.jpeg)
>If you are using **CM5** and require **USB3.0**, make sure to leave one slot empty between modules to ensure proper USB 3.0 functionality.
### M4N Installation
- First, install the M4N core module onto the adapter board
![m4n_mount1](../../../zh/cluster/NanoCluster/assets/m4n_mount1.jpeg)
- Then insert the adapter board into the mainboard slot
![m4n_mount2](../../../zh/cluster/NanoCluster/assets/m4n_mount2.jpeg)
### Fan Installation
Align the fan with the reserved mounting holes on the baseboard:
![fan1](../../../zh/cluster/NanoCluster/assets/fan1.jpeg)
Make sure the fan is facing the correct direction — the airflow should point toward the Ethernet port to better dissipate heat from the SOM:
![fan2](../../../zh/cluster/NanoCluster/assets/fan2.jpeg)
Secure the fan firmly to the baseboard using screws:
![fan3](../../../zh/cluster/NanoCluster/assets/fan3.jpeg)
Connect the fan's power cable to the fan power connector on the baseboard.
Please ensure the correct plug orientation — the red wire should be connected to the positive terminal:
![fan4](../../../zh/cluster/NanoCluster/assets/fan4.jpeg)
## Power Supply
NanoCluster supports both USB-C PD and PoE power input, with dual hot-plug capability — you can connect both PD and PoE at the same time, and the system will remain stable even if one source is disconnected. Either power source can be plugged or unplugged at any time.
By default, the system supports 60W (20V/3A) PD input, and up to 65W (20V/3.25A) when using e-Marker USB-C cables. We recommend using the included PD adapter and high-quality USB-C cables to ensure stable power delivery. An optional 60W peak / 50W sustained PoE module is available for deployments where dedicated power access is limited.
### Max Supported Configurations (Based on Power Budget):
| Power Source | Max Supported SOMs |
|--------------|-----------------------------------|
| PD | 7× LM3H / CM4 / CM5 / M4N |
| PoE | 7× LM3H / CM4; 6× CM5 / M4N |
| SSD Installed| Up to 4× SOMs with SSDs (space-limited) |
<br>
> **Note:** CM5 and M4N modules have higher power consumption. When using PoE, it is recommended to connect no more than 6 of these.
---
### PD Port Description
The board supports USB-C PD power input, with a maximum of 65W. Please use the official adapter or a third-party adapter rated at 20V/3A or higher to ensure reliable operation under full load.
![pd](../../../zh/cluster/NanoCluster/assets/pd_power.jpeg)
---
### PoE Module Installation
NanoCluster supports an optional PoE module for power-over-Ethernet deployment, helping simplify wiring. Please follow the diagrams below for proper installation:
![poe1](../../../zh/cluster/NanoCluster/assets/poe1.jpeg)
Align the PoE module with the mainboard socket and insert carefully. Ensure a firm and secure connection.
![poe2](../../../zh/cluster/NanoCluster/assets/poe2.jpeg)
> Use a PoE switch or adapter compliant with standard protocols to ensure safety and stability.
## Flashing the Image
##### The core board comes with a pre-installed system. If you need to reflash the system, follow the steps below:
### LM3H Flashing
Download the required firmware image and prepare a computer that supports USB OTG along with a USB cable. The NanoCluster currently uses images compatible with the Longan Pi 3H, which can be downloaded here: [Click to Download](https://wiki.sipeed.com/hardware/en/longan/h618/lpi3h/3_images.html).
Insert the core board into the Slot1 position, then use a USB cable to connect the mainboard's OTG interface (the lower port) to the computer. Press and hold the BOOT button, then power on or reset the device to enter UMS flashing mode.
![flash_lm3h_1](../../../zh/cluster/NanoCluster/assets/flash_lm3h_1.jpeg)
Once the firmware image is ready, open balenaEtcher, select the image file to be flashed, and ensure the core board is recognized as a USB drive. In balenaEtcher, choose the target device, click the "Flash" button to start the flashing process, and wait for it to complete. Safely eject the device, disconnect the USB cable, and restart the device to boot into the new system.
![flash_lm3h_2](../../../zh/cluster/NanoCluster/assets/flash_lm3h_2.jpeg)
### CM4/CM5 Flashing
1. Install the `rpiboot` tool following the [official documentation](https://www.raspberrypi.com/documentation/computers/compute-module.html#set-up-the-host-device).
2. Press and hold the BOOT button on the adapter board, then connect the USB OTG port to your host computer.
3. Once the host detects a **BCM2711 (BCM2712) Boot** device, run `rpiboot`. After a few seconds, a USB drive will automatically appear.
4. Open the [Raspberry Pi Imager](https://www.raspberrypi.com/software/), select the desired image, and flash it to the detected device.
### M4N Flashing
You can refer to the [System Flashing Guide](https://wiki.sipeed.com/hardware/zh/maixIV/m4ndock/system-update.html) for the flashing process.
## Remote Management
The mainboard is equipped with an Ethernet port for connecting to a switch. Devices within the cluster are interconnected through the switch and can be controlled and managed via their IP addresses.
**How to obtain the device's IP address (using the LM3H module as an example)**:
First, connect the Ethernet cable to the mainboard's port, then power on the device. The pre-installed firmware has mDNS service enabled. On your PC, enable the Avahi service and use mDNS to scan the entire network to retrieve the mDNS domain name information of the lpi3h device.
```bash
avahi-browse -art | grep lpi3h
```
Then use the following command:
```bash
ssh sipeed@lpi3h-xxxx.local
```
to connect (replace `xxxx` with the hostname obtained using the `avahi-browse` command).
> lpi3h is the default mDNS hostname prefix for LM3H. If you are using CM4 or CM5, please adjust the hostname according to the system image you have flashed.
## Serial Connection
Each SOM exposes the system serial port to a 2.54mm header, which can be connected for debugging using a serial-to-USB module.
If you need to debug or control multiple slots simultaneously, we recommend using the USB to four serial ports expansion board we provide. This expansion board consolidates the serial signals from slot3, slot5, slot6, and slot7 into the USB interface of slot1, making it easier to manage and operate centrally.
![uart_board](../../../zh/cluster/NanoCluster/assets/uart.jpeg)
## Power Control
The reset pins for slots 1~7 are controlled by slot 1 through **I2C extended IO**, enabling remote power on/off functionality.
**LM3H Control Method Example:**
```bash
# Reset the switch chip (GPIO 0)
sudo gpioset gpiochip2 0=0 && sudo gpioset gpiochip2 0=1
# Reset slot2 (LM3H)
# Hold for 8 seconds to power off
sudo gpioset gpiochip2 2=0 && sleep 8 && sudo gpioset gpiochip2 2=1
# Quick trigger to power on
sudo gpioset gpiochip2 2=0 && sleep 1 && sudo gpioset gpiochip2 2=1
# Reset slot2 (CM4/CM5)
sudo gpioset gpiochip2 2=0 && sudo gpioset gpiochip2 2=1
```
> `gpiochip2` refers to the GPIO controller index. `x=0` sets the IO with index `x` to low level, while `x=1` sets it to high level.
| GPIO Index | Function |
|------------|-------------------|
| 0 | Switch chip reset |
| 1~7 | slot1~slot7 reset |
**CM4/CM5 Control Method Example:**
todo。
## Fan Speed Adjustment
LM3H / CM4 / CM5 all support fan speed control. By default, LM3H automatically adjusts fan speed based on CPU temperature, while the official images of CM4 and CM5 run the fan at full speed. Below are the control methods for each platform.
If you want to manually control the fan, you can connect to the slot1 device via SSH and execute the following commands:
### LM3H Fan Control
``` bash
echo disabled | sudo tee /sys/class/thermal/thermal_zone2/mode
echo 4 | sudo tee /sys/class/thermal/cooling_device0/cur_state
```
The value of `cur_state` ranges from 0 to 4, representing different fan speeds.
To restore automatic control, use the following command:
``` bash
echo enabled | sudo tee /sys/class/thermal/thermal_zone2/mode
```
### CM4 Fan Control
Add the following line to /boot/config.txt:
```bash
dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4
```
After rebooting, execute:
``` bash
sudo pigpiod
```
Control the fan using Python:
```python
import pigpio
pi = pigpio.pi()
# Set PWM frequency and range
pi.set_PWM_frequency(13, 50)
pi.set_PWM_range(13, 200)
# Set fan speed
pi.set_PWM_dutycycle(13, 0) # Off
pi.set_PWM_dutycycle(13, 200) # Full speed
```
### CM5 Fan Control
Control the fan using Python:
```python
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(13, GPIO.OUT)
pwm = GPIO.PWM(13, 50) # 50Hz frequency
pwm.start(0) # Off
pwm.start(100) # Full speed
```
## Switch Management
### Introduction
NanoCluster is equipped with the JL6108 Gigabit switch chip, which is based on the **RISC-V** architecture. It can be used as a plug-and-play switch or as a locally managed Layer 2 switch, supporting configuration via a web interface. Its main features include:
- **System Management**: Displays system information, supports reboot, factory reset, and firmware upgrades
- **Network Configuration**: Supports static IP and DHCP dynamic IP configuration
- **Port Management**: Enables/disables ports, configures link speed, and manages flow control
- **Port Aggregation**: Supports port binding to increase bandwidth utilization
- **Security and Isolation**: Port isolation to prevent data leakage
- **Traffic Monitoring**: Port MIB statistics and traffic analysis
- **Loop Protection**: Prevents network loops to enhance stability
- **VLAN Configuration**: Supports MTU VLAN, port-based VLAN, 802.1Q VLAN, and PVID settings
- **QoS Configuration**: Manages traffic priority based on port, PCP, and DSCP
- **Bandwidth and Storm Control**: Supports port-based bandwidth limitation and broadcast storm suppression
### User Guide
#### Logging into the Web Management Interface
1. **Ensure Device Connection**
Make sure the NanoCluster is powered on and connected to the management host via an Ethernet cable.
2. **Configure IP Address**
The switch's default IP address is **10.10.11.10/24**. Ensure the management host has an IP in the same subnet, e.g., **10.10.11.x** (where x is between 1-254 but not 10), with a subnet mask of **255.255.255.0**.
![IP Configuration](../../../zh/cluster/NanoCluster/assets/ip.jpeg)
3. **Access the Management Interface**
Open a browser and enter `http://10.10.11.10`, then press Enter to reach the login page.
![Login Page](../../../zh/cluster/NanoCluster/assets/login.jpeg)
4. **Login to the Management System**
Enter the **admin username and password** (both default to `admin`), then click **Login** to access the main interface.
![Management Homepage](../../../zh/cluster/NanoCluster/assets/homepage.jpeg)
### Basic Configuration
#### Port Management
The JL6108 switch provides port status management, supporting **port enable/disable**, **speed configuration**, and **flow control**.
- **Enable/Disable Ports**: Navigate to the **Port Management** page, select the desired port, and enable or disable it.
- **Modify Port Speed**: Supports 10Mbps / 100Mbps / 1000Mbps modes.
- **Flow Control**: Can be enabled to prevent packet loss.
![Port Management](../../../zh/cluster/NanoCluster/assets/portsetting.jpeg)
#### VLAN Configuration
VLAN (Virtual Local Area Network) is used to segment different network areas, prevent broadcast storms, and enhance security.
##### Configuring Port VLAN
1. **Access the Port VLAN Page**
Navigate to `VLAN` >> `Port VLAN` in the Web interface.
2. **Enable Port VLAN**
Check the **"Enable Port VLAN"** option and click **`Apply`**.
3. **Create VLAN 2 and Assign Ports**
- Enter **`2`** in the **VLAN ID** field
- Select **Ports 2 to 4**
- Click **`Apply`** to save the configuration
4. **View the Port Member Table**
After configuration, **Ports 2-4 will be automatically removed from VLAN 1** and assigned to VLAN 2.
![Port VLAN Configuration](../../../zh/cluster/NanoCluster/assets/vlan.jpeg)
#### QoS Configuration (Traffic Prioritization)
QoS ensures stable performance for high-priority traffic such as video conferencing and VoIP:
1. **Navigate to "QoS Settings"**
2. Select **Port-Based / 802.1P / DSCP** QoS strategy
3. Set **High / Medium / Low Priority Queues**
4. **Save the settings** to apply the QoS rules
![QoS Configuration](../../../zh/cluster/NanoCluster/assets/qos.jpeg)
### Additional Configuration
The JL6108 switch also supports more advanced features. For detailed configuration instructions, please refer to the official manual.
[Click here to view the full manual](https://dl.sipeed.com/shareURL/Cluster/NanoCluster/06_Switch_JL6108)
We provide the **JL6108 SDK** based on the **RISC-V** architecture. Users can download the SDK and develop independently from the following link:
[JL6108 SDK](https://dl.sipeed.com/shareURL/Cluster/NanoCluster/06_Switch_JL6108)
## FAQ (Troubleshooting)
### Device Won't Power On / Can't Boot into System
Ensure you are using a power adapter that supports at least PD 20V output. Avoid using USB power from a host device, as this may prevent the device from starting properly. Check if the green indicator light near the power input interface is lit. If there is no response, the issue may lie with the power adapter or power cable. Observe the blue power indicator lights corresponding to each slot to determine if the system has started normally.
If **LM3H** fails to boot into the system, press and hold the BOOT button while powering on or resetting the device to check if it enters UMS mode. Confirm whether the device is recognized as a USB drive in disk management. If the system is damaged or cannot boot, you can reflash the [firmware image](https://wiki.sipeed.com/hardware/en/NanoCluster/use.html#Flashing-the-Image). If UMS mode cannot be entered, try the [emergency flashing](https://wiki.sipeed.com/hardware/en/cluster/NanoCluster/use.html#Emergency-Flashing-(LM3H)) method.
If **CM4/CM5** fails to start normally, you can re-flash the system image following the instructions in the [firmware image](https://wiki.sipeed.com/hardware/en/cluster/NanoCluster/use.html#Flashing-the-Image) section and test again.
### Network Connection Issues (Unable to Obtain IP)
If the system boots successfully but there are network connection issues or the device cannot obtain an IP address, ensure the Ethernet cable is connected before powering on the device. Switches detect network interfaces when the device powers on. Plugging in the Ethernet cable after powering on may cause the interface to fail to recognize the connection.
### Emergency Flashing (LM3H)
If U-Boot is corrupted and the device cannot enter UMS mode, you can manually recover it using FEL mode. Use the `sunxi-fel` or `xfel` tools to load U-Boot into memory and start UMS mode, then proceed with flashing.
#### Entering FEL Mode
Short the specified pin on slot1 to GND, then power on the device to enter FEL mode (future versions may add button control).
![fel](../../../zh/cluster/NanoCluster/assets/fel.jpeg)
#### Using sunxi-fel
Install and compile:
```bash
git clone https://github.com/linux-sunxi/sunxi-tools.git
cd sunxi-tools
make tools
sudo make install
```
Flash U-Boot:
```bash
sudo sunxi-fel uboot /path/u-boot-sunxi-with-spl.bin
```
After completing the process, the device should enter UMS mode successfully, allowing you to proceed with flashing the system image.
#### Using xfel
Install and compile:
```bash
sudo apt install libusb-1.0-0-dev
git clone https://github.com/xboot/xfel.git
cd xfel
make
sudo make install
```
Flash U-Boot:
```bash
xfel ddr lpddr4
xfel write 0x4a000000 /path/u-boot-dtb.bin
xfel exec 0x4a000000
```
After completing the process, the device should enter UMS mode successfully, allowing you to flash the system image.

14
docs/hardware/en/sidebar.yaml
View File

@@ -496,6 +496,20 @@ items:
file: kvm/NanoKVM_USB/development.md
- label: FAQ
file: kvm/NanoKVM_USB/faq.md
- label: Cluster
items:
- label: NanoCluster
items:
- label: Introduction
file: cluster/NanoCluster/index.md
- label: Quick Start
file: cluster/NanoCluster/use.md
- label: Application Development
items:
- label: k3s Deployment
file: cluster/NanoCluster/k3s.md
- label: distcc Deployment
file: cluster/NanoCluster/distcc.md
# - label: Maix Audio
# items:
# - label: MA USB 16

BIN
docs/hardware/zh/cluster/NanoCluster/assets/bare_board.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/board_io.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/cm4_mount1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/cm4_mount2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/fan1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/fan2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/fan3.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/fan4.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/fel.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 143 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/flash_lm3h_1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/flash_lm3h_2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/hello_k3s.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/homepage.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/ip.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/login.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/m4n_mount1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/m4n_mount2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/mount1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/mount2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/pd_power.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/poe1.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/poe2.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/portsetting.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/product.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/qos.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/som.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 92 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/uart.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
docs/hardware/zh/cluster/NanoCluster/assets/vlan.jpeg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

86
docs/hardware/zh/cluster/NanoCluster/distcc.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: distcc 部署
---
## 简介
[distcc](https://github.com/distcc/distcc) 是一个分布式 C/C++ 编译系统，它通过将编译任务分发到多台机器上来加速编译过程。它允许你利用多台计算机的计算能力，更快速地编译代码，特别适用于大型代码库或资源受限的设备环境。
## 部署教程
### 服务端
对于 Debian 系统,可以直接使用包管理器安装 distcc
```bash
sudo apt install distcc
```
开启 distcc 服务
```bash
distccd --daemon --allow 192.168.0.0/24 # 允许特定 IP 范围的机器访问
```
### 客户端
```bash
sudo apt install distcc distcc-pump
```
配置 DISTCC_HOSTS 环境变量，指定可用的工作节点。可以在 .bashrc 中添加以下内容：
```bash
export DISTCC_POTENTIAL_HOSTS='localhost 192.168.0.240 192.168.0.243 192.168.0.245 192.168.0.246'
```
然后，可以尝试编译一个简单的程序，检查 distcc 是否正常分发编译任务：
```bash
distcc-pump distcc -o test test.c
```
```bash
sipeed@lpi3h-a2d1:~/distcc$ distcc-pump distcc -o test test.c
__________Using distcc-pump from /usr/bin
__________Found 4 available distcc servers
__________Shutting down distcc-pump include server
```
## 编译测试
为了测试 distcc 是否能够有效地加速编译过程，我们使用 OpenSSL 来进行编译测试。OpenSSL 是一个广泛使用的 C 库，包含大量源代码，适合用来测试分布式编译的效果。
```bash
git clone https://github.com/openssl/openssl.git
cd openssl
./config
distcc-pump make -j20 CC=distcc
```
可以使用 distccmon-text 查看当前编译任务的分发情况
```bash
sipeed@lpi3h-2193:~$ distccmon-text
67535 Compile cmp_ctx.c 192.168.0.240[0]
67528 Compile cmp_asn.c 192.168.0.240[1]
67635 Compile cms_dh.c 192.168.0.240[2]
67569 Compile cmp_http.c 192.168.0.243[0]
67696 Compile cms_io.c 192.168.0.245[0]
67583 Compile cmp_server.c 192.168.0.245[1]
67561 Compile cmp_hdr.c 192.168.0.245[2]
67606 Compile cmp_vfy.c 192.168.0.245[3]
67657 Compile cms_enc.c 192.168.0.246[1]
67672 Compile cms_env.c 192.168.0.246[2]
```
### 编译性能对比
在测试过程中，我们对 OpenSSL 项目分别使用了单机编译和分布式编译（5台机器），下面是两种方式的编译结果：
##### 单机编译（不使用 distcc）
```bash
real 18m11.760s
user 64m37.024s
sys 5m56.326s
```
##### 分布式编译（使用 distcc）
```bash
real 6m32.262s
user 18m39.468s
sys 4m30.008s
```
可以看到，使用 distcc 进行分布式编译后，编译时间显著缩短，从 18 分钟降至约 6 分钟。可见分布式编译的加速效果明显，同时也可以有效地减轻单个机器的负载。

190
docs/hardware/zh/cluster/NanoCluster/index.md Normal file
View File

@@ -0,0 +1,190 @@
---
title: 简介
---
## 简介
NanoCluster 是矽速科技开发的超迷你集群板，板载 7 个 SOM 插槽，采用基于 RISC-V 架构的千兆交换机互联，支持 USB-C PD 供电，并可扩展 PoE 供电。同时，NanoCluster 提供独立的 UART 和电源控制，使其成为 HomeLab 用户入门分布式计算、Kubernetes 和 Docker 实践，以及边缘计算的理想选择。
NanoCluster 兼容矽速科技的 Longan Module 3H（4 × Cortex-A53）、M4N（4 × Cortex-A55 + NPU），以及树莓派的 Compute Module 4（4 × Cortex-A72） 和 Compute Module 5（4× Cortex-A76）。用户可以根据性能需求和预算自由选择核心板，也可以混合搭配不同架构的核心板，构建一个高度定制化的计算集群。
NanoCluster 采用开放的 SOM 接口标准，不仅支持官方核心板，也允许用户自行设计转接板，以适配自定义核心板或其他第三方 SOM 方案，极大提升了平台的灵活性。
<br>
![产品特写图](./assets/product.png)
## 技术规格
### 底板
<table>
<thead>
<tr>
<th colspan="2">硬件参数</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>SOM 插槽</strong></td>
<td>7× 双 M.2 M-Key 立式插槽</td>
</tr>
<tr>
<td><strong>供电</strong></td>
<td>USB-C 20V PD 供电，最大 60W，可选配 60W PoE 模块供电</td>
</tr>
<tr>
<td><strong>以太网</strong></td>
<td>板载 RISC-V 千兆交换芯片 JL6108 高速互联，支持 Web 页面管理和 SDK 自定义功能开发</td>
</tr>
<tr>
<td><strong>USB 接口</strong></td>
<td>USB-A Host（上），USB-A OTG（下），与 Slot 1 连接</td>
</tr>
<tr>
<td><strong>显示接口</strong></td>
<td>HDMI 接口，与 Slot 1 连接</td>
</tr>
<tr>
<td><strong>散热系统</strong></td>
<td>配备 60mm 2Pin 风扇，高效散热</td>
</tr>
<tr>
<td><strong>状态指示</strong></td>
<td>7× SYS LED 指示灯，用于各个计算节点状态监测</td>
</tr>
<tr>
<td><strong>串口通信</strong></td>
<td>7× 独立 UART，便于调试与控制，可选配四串口 USB 模块</td>
</tr>
<tr>
<td><strong>电源管理</strong></td>
<td>Slot1 通过 IO 扩展芯片集中管理其他 Slot 及交换机电源</td>
</tr>
<tr>
<td><strong>功耗</strong></td>
<td>3.6 W</td>
</tr>
<tr>
<td><strong>尺寸</strong></td>
<td>PCBA：88x57mm，插满 SOM 并安装风扇后约 100x60x60mm</td>
</tr>
</tbody>
</table>
![底板裸板特写图](./assets/bare_board.jpeg)
### SOM
<table>
<tr>
<th>SOM</th>
<th>LM3H</th>
<th>M4N</th>
<th>CM4</th>
<th>CM5</th>
</tr>
<tr>
<td>主控芯片</td>
<td>H618</td>
<td>AX650N</td>
<td>BCM2711</td>
<td>BCM2712</td>
</tr>
<tr>
<td>内存</td>
<td>2GB ~ 4GB</td>
<td>8GB</td>
<td>1GB ~ 8GB</td>
<td>1GB ~ 16GB</td>
</tr>
<tr>
<td>eMMC</td>
<td>32GB</td>
<td>32GB</td>
<td>0GB ~ 64GB</td>
<td>0GB ~ 64GB</td>
</tr>
<tr>
<td>CPU</td>
<td>4 × A53<br>1.5 GHz</td>
<td>8 × A55<br>1.6 GHz</td>
<td>4 × A72<br>1.5 GHz</td>
<td>4 × A76<br>2.4 GHz</td>
</tr>
<tr>
<td>GPU</td>
<td>Mali-G31</td>
<td>-</td>
<td>VideoCore VI</td>
<td>VideoCore VII</td>
</tr>
<tr>
<td>NPU</td>
<td>-</td>
<td>18TOPS INT8</td>
<td>-</td>
<td>-</td>
</tr>
<tr>
<td>网络连接</td>
<td>百兆</td>
<td>千兆</td>
<td>千兆</td>
<td>千兆</td>
</tr>
<tr>
<td>其它接口</td>
<td>None</td>
<td>下载接口 + M.2 SSD + USB 3.0</td>
<td>下载接口 + M.2 SSD</td>
<td>下载接口 + M.2 SSD + USB 3.0</td>
</tr>
<tr>
<td>功耗<br>空载 /<br>满载 /<br>峰值</td>
<td><nobr>1.2W/2.6W/3.7W</nobr></td>
<td><nobr>3W/8.3W/9W</nobr></td>
<td><nobr>3W/4.5W/4.6W</nobr></td>
<td><nobr>4W/7.6W/8W</nobr></td>
</tr>
</table>
![SOM图](./assets/som.jpeg)
## 接口图示
![接口图示](./assets/board_io.jpeg)
## 软硬件资料
### 底板硬件资料
[点击查看](https://dl.sipeed.com/Cluster/NanoCluster)
### Longan Module 3H 资料
硬件资料可在此获取：[点击查看](https://dl.sipeed.com/shareURL/LONGAN/LonganPi3H)。系统构建与软件开发指南请参考：[点击这里](https://wiki.sipeed.com/hardware/zh/longan/h618/lpi3h/7_develop_mainline.html)。
### M4N 资料
+ [硬件相关资料](https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock)
+ [软件开发文档](https://dl.sipeed.com/shareURL/MaixIV/M4N-Dock)
+ [软件开发SDK](https://github.com/AXERA-TECH/ax650n_bsp_sdk)
### Raspberry Pi Compute Module 4
[点击查看](https://www.raspberrypi.com/products/compute-module-4)
### Raspberry Pi Compute Module 5
[点击查看](https://www.raspberrypi.com/products/compute-module-5)
## 购买入口
[预售入口](https://sipeed.com/nanocluster)
## 产品反馈
如果您在使用过程中有任何问题或建议，请通过以下渠道和我们反馈：
+ [Github issues](https://github.com/sipeed/NanoCluster)

116
docs/hardware/zh/cluster/NanoCluster/k3s.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: K3s 部署
---
## 简介
[K3s](https://k3s.io/) 是轻量级的 Kubernetes。它易于安装，仅需要 Kubernetes 内存的一半，适用于资源有限的环境，特别是边缘计算、物联网等应用场景。
## 部署教程
### 准备环境
首先，确保集群的网络正常，并且能够访问互联网。你可以使用 SSH 远程登录到集群中的每台机器，执行后续安装命令。确保主节点和工作节点的 IP 地址固定，并且网络间能够互相访问。
### 安装 K3s（主节点）
K3s 的安装非常简单。你只需在主节点上运行以下命令：
``` bash
curl -sfL https://get.k3s.io | sh -
```
如果下载很慢可以使用以下命令加速安装
``` bash
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -
```
该命令会自动下载并安装 K3s。安装过程完成后，通过以下命令检查 K3s 服务是否启动：
``` bash
sudo systemctl status k3s
```
如果显示 `active (running)`，表示 K3s 已成功启动。
```bash
sudo systemctl status k3s
● k3s.service - Lightweight Kubernetes
Loaded: loaded (/etc/systemd/system/k3s.service; enabled; preset: enabled)
Active: active (running) since Mon 2025-02-17 12:07:15 CST; 3h 38min ago
Docs: https://k3s.io
Process: 8803 ExecStartPre=/bin/sh -xc ! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null (code=exited, status=0/SUCCESS)
Process: 8805 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
Process: 8808 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
Main PID: 8810 (k3s-server)
Tasks: 32
Memory: 583.2M
CPU: 29min 49.755s
CGroup: /system.slice/k3s.service
├─8810 "/usr/local/bin/k3s server"
└─8895 "containerd "
```
### 安装 K3s（工作节点）
在工作节点上安装 K3s 时，需要将工作节点与主节点连接。使用以下命令在工作节点上安装 K3s：
``` bash
curl -sfL https://get.k3s.io | K3S_URL=https://<主节点IP>:6443 K3S_TOKEN=<主节点Token> sh -
```
上述命令中，`主节点IP` 需要替换为主节点的 IP 地址，`主节点Token` 是从主节点获取的令牌。你可以通过以下命令在主节点上查看令牌：
```bash
sudo cat /var/lib/rancher/k3s/server/node-token
```
安装完成后，使用以下命令验证工作节点是否成功加入集群：
```bash
sudo kubectl get nodes
```
如果工作节点显示在列表中，且状态为 `Ready`，则表示工作节点成功加入集群。
```bash
sipeed@lpi3h-a2d1:~$ sudo kubectl get nodes
NAME STATUS ROLES AGE VERSION
lpi3h-1967 Ready <none> 20h v1.31.5+k3s1
lpi3h-231e Ready <none> 20h v1.31.5+k3s1
lpi3h-4782 Ready <none> 56m v1.31.5+k3s1
lpi3h-a2d1 Ready control-plane,master 23h v1.31.5+k3s1
lpi3h-ba13 Ready <none> 19h v1.31.5+k3s1
lpi3h-c06b Ready <none> 21h v1.31.5+k3s1
```
### 部署应用
我们新建一个配置文件，用于运行 k3s 容器
```bash
nano hello-kubernetes.yaml
```
文件内容如下：
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-kubernetes
spec:
replicas: 1
selector:
matchLabels:
app: hello-kubernetes
template:
metadata:
labels:
app: hello-kubernetes
spec:
containers:
- name: hello-kubernetes
image: paulbouwer/hello-kubernetes:1.10.1
env:
- name: MESSAGE
value: "Hello Kubernetes"
```
然后使用这个配置文件启动一个容器
```bash
sudo kubectl apply -f hello-kubernetes.yaml
```
查看 pods 状态
```bash
sudo kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
hello-kubernetes-7fbb7f4899-zqs5x 1/1 Running 0 2m39s 10.42.0.114 arch <none> <none>
```
通过浏览器访问 10.42.0.114:8080
![hello_k3s](./assets/hello_k3s.jpeg)

400
docs/hardware/zh/cluster/NanoCluster/use.md Normal file
View File

@@ -0,0 +1,400 @@
---
title: 快速上手
---
## 硬件安装
### LM3H 安装
先将散热片粘贴到主控芯片上，以提升散热效果。安装核心板时，请确保方向正确，以免损坏设备。
![mount1](./assets/mount1.jpeg)
对准核心板上的金手指缺口与主板卡槽，使其对齐后轻轻放入，并均匀向下按压，直至听到 “喀哒” 声，确认核心板已牢固插入且无歪斜或松动。
![mount2](./assets/mount2.jpeg)
如需拆卸核心板，请双手均匀握住核心板两侧，轻轻向上施力，避免单侧用力过大导致损坏。若核心板较紧，可先左右轻微晃动后再拔出，切勿生拉硬拽，以防损坏金手指或主板卡槽。
### CM4、CM5 安装
- 先将 CM4 / CM5 安装到转接板上；
![cm4_mount1](./assets/cm4_mount1.jpeg)
- 再将转接板插入主板插槽。
![cm4_mount2](./assets/cm4_mount2.jpeg)
>若使用 **CM5** 且需支持 **USB3.0**，请间隔一个槽位安装，确保 USB3 通道正常工作。
### M4N 安装
- 先将 M4N 核心板安装到转接板上；
![m4n_mount1](./assets/m4n_mount1.jpeg)
- 再将转接板插入主板插槽。
![m4n_mount2](./assets/m4n_mount2.jpeg)
### 风扇安装
将风扇对准底板上预留的安装孔位插入：
![fan1](./assets/fan1.jpeg)
请确保风扇朝向正确，风向应朝向网口方向，以便更有效地带走 SOM 的热量：
![fan2](./assets/fan2.jpeg)
使用螺丝将风扇牢固固定在底板上：
![fan3](./assets/fan3.jpeg)
将风扇的电源排线插入底板上的风扇供电接口。请注意插头方向，确保红线为正极：
![fan4](./assets/fan4.jpeg)
## 电源供应
NanoCluster 支持 USB-C PD 与 PoE 两种供电方式，支持双路热插拔 —— 即可同时连接 PD 与 PoE，在断开其中任意一方后系统依然稳定运行，支持在任意时刻插入或拔出任一电源。
默认支持 60W（20V/3A）PD 供电，使用带 e-Marker 的线材可达 65W（20V/3.25A）。推荐使用标配的 PD 适配器及优质 USB-C 线缆，以确保稳定供电。可选配 60W 峰值功率的 PoE 模块，持续输出功率约为 50W，适用于无独立供电接口的网络部署环境。
### 最大支持配置（参考推荐功率）：
| 供电方式 | 最大支持配置 |
|----------|----------------------------------|
| PD | 支持 7× LM3H / CM4 / CM5 / M4N |
| PoE | 支持 7× LM3H / CM4；6× CM5 / M4N |
| SSD 安装 | 最多支持 4 个带 SSD 的 SOM（因空间限制）|
<br>
> **注：** CM5 / M4N 模块因功耗更高，在 PoE 模式下建议最多连接 6 个。
---
### PD 接口说明
设备通过 USB-C 接口支持 PD 协议供电，最大功率 65W。请使用原装适配器或符合 20V/3A 以上规格的电源适配器，确保设备正常启动并满载运行。
![pd](./assets/pd_power.jpeg)
---
### PoE 模块安装说明
NanoCluster 可选配 PoE 模块，实现网络线供电，简化布线部署。请参考下图进行正确安装：
![poe1](./assets/poe1.jpeg)
将 PoE 模块与主板插槽对齐后小心插入，确保连接牢靠，不松动。
![poe2](./assets/poe2.jpeg)
>请使用符合标准的 PoE 交换机或 PoE 适配器，以保证稳定性和安全性。
## 烧录镜像
##### 核心板默认已预装系统，如需重新烧录系统，可按照以下步骤进行操作：
### LM3H 烧录
下载所需的固件镜像，并准备一台支持 USB OTG 的计算机及 USB 线。NanoCluster 目前使用的镜像与 Longan Pi 3H 兼容，可在此获取：[点击下载](https://wiki.sipeed.com/hardware/zh/longan/h618/lpi3h/3_images.html)。
将核心板插入 slot1 槽位后，使用 USB 线 连接 主板 OTG 接口（下方的接口）与计算机。按住 BOOT 按键，然后 上电或复位设备，即可进入 UMS 烧录模式。
![flash_lm3h_1](./assets/flash_lm3h_1.jpeg)
准备好固件镜像后，打开 balenaEtcher，选择要烧录的镜像文件，确保核心板被识别为 U 盘，然后在 balenaEtcher 中选择目标设备。点击 “Flash” 按钮开始烧录，等待烧录完成后，安全弹出设备，断开 USB 连接并重启设备，即可进入新系统。
![flash_lm3h_2](./assets/flash_lm3h_2.jpeg)
### CM4/CM5 烧录
1. 按照 [官方文档](https://www.raspberrypi.com/documentation/computers/compute-module.html#set-up-the-host-device) 安装 `rpiboot` 工具。
2. 按住转接板上的 BOOT 按键，将 USB OTG 接口连接到主机。
3. 主机识别到 **BCM2711 (BCM2712) Boot** 设备后，运行 `rpiboot`，稍等片刻会自动弹出一个 U 盘设备。
4. 打开 [Raspberry Pi Imager](https://www.raspberrypi.com/software/)，选择所需镜像并烧录到该设备上即可。
### M4N 烧录
可参考[系统烧录指南](https://wiki.sipeed.com/hardware/zh/maixIV/m4ndock/system-update.html)进行烧录
## 远程管理
主板配备一个网口用于连接交换机，集群内部设备通过交换机互联，并可通过 IP 地址进行控制和管理。
**如何获得设备的IP地址（以 LM3H 核心板为例）**:
先将网线连接至主板的网口，然后上电。预装的固件已启用 mDNS 服务，可在 PC 上启用 Avahi 服务，并使用 mDNS 扫描整个网络，即可获取 lpi3h 设备的 mDNS 域名信息。
``` bash
avahi-browse -art | grep lpi3h
```
然后使用:
``` bash
ssh sipeed@lpi3h-xxxx.local
```
即可连接（将 xxxx 替换为使用 avahi-browse 命令查看到的主机名）
> lpi3h 为 LM3H 默认的 mDNS 主机名前缀，若使用的是 CM4 或 CM5，请根据所烧录的系统镜像自行调整主机名。
## 串口连接
每个 SOM 都将系统串口引出至 2.54mm 插针，可通过串口转 USB 模块进行连接调试。
如需同时调试或控制多个 slot，推荐使用我们提供的 USB 转四串口扩展板。该扩展板将 slot3、slot5、slot6 和 slot7 的串口信号统一接入 slot1 的 USB 接口，便于集中管理与操作。
![串口小板](./assets/uart.jpeg)
## 电源控制
slot1~7 的复位脚由 slot1 通过 **I2C 扩展的 IO** 进行控制，可实现远程开关机。
**LM3H 控制方法示例：**
```bash
# 复位交换机芯片（GPIO 0）
sudo gpioset gpiochip2 0=0 && sudo gpioset gpiochip2 0=1
# 复位 slot2（LM3H）
# 长按 8 秒实现关机
sudo gpioset gpiochip2 2=0 && sleep 8 && sudo gpioset gpiochip2 2=1
# 快速触发实现开机
sudo gpioset gpiochip2 2=0 && sleep 1 && sudo gpioset gpiochip2 2=1
# 复位 slot2（CM4/CM5）
sudo gpioset gpiochip2 2=0 && sudo gpioset gpiochip2 2=1
```
> `gpiochip2` 表示 GPIO 控制器编号，后面的 `x=0` 表示将编号为 x 的 IO 设置为低电平，`x=1` 设置为高电平。
| GPIO 编号 | 对应功能 |
|-----------|------------------|
| 0 | 交换机芯片复位 |
| 1~7 | slot1~slot7 复位 |
**CM4/CM5 控制方法示例：**
todo。
## 风扇调速
LM3H / CM4 / CM5 均支持风扇调速，默认情况下 LM3H 会根据 CPU 温度自动调节转速, CM4 和 CM5 官方镜像默认风扇全速运行。以下为各平台的控制方法。
如果需要手动调节风扇，可通过 SSH 连接到 slot1 设备，并执行以下命令：
### LM3H 调速
``` bash
echo disabled | sudo tee /sys/class/thermal/thermal_zone2/mode
echo 4 | sudo tee /sys/class/thermal/cooling_device0/cur_state
```
`cur_state` 取值范围为 0 ~ 4，对应不同转速。
如果要恢复自动调节，可使用以下命令:
``` bash
echo enabled | sudo tee /sys/class/thermal/thermal_zone2/mode
```
### CM4 调速
将以下内容添加到 /boot/config.txt:
```bash
dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4
```
重启后执行：
``` bash
sudo pigpiod
```
Python 控制风扇：
```python
import pigpio
pi = pigpio.pi()
# 设置 PWM 频率和范围
pi.set_PWM_frequency(13, 50)
pi.set_PWM_range(13, 200)
# 设置风扇转速
pi.set_PWM_dutycycle(13, 0) # 不转
pi.set_PWM_dutycycle(13, 200) # 满速
```
### CM5 调速
Python 控制风扇：
```python
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
GPIO.setup(13, GPIO.OUT)
pwm = GPIO.PWM(13, 50) # 50Hz 频率
pwm.start(0) # 不转
pwm.start(100) # 满速
```
## 交换机管理
### 简介
NanoCluster 搭载 JL6108 千兆交换机芯片，该芯片基于 **RISC-V** 架构，既可作为即插即用的傻瓜交换机使用，也可作为可本地管理的二层交换机，支持通过 Web 进行配置。主要功能包括：
- **系统管理**：显示系统信息、支持重启、恢复出厂设置、固件升级
- **网络配置**：支持静态 IP 和 DHCP 动态 IP 配置
- **端口管理**：端口启用/禁用、链路速率设置、流控管理
- **端口汇聚**：支持端口绑定，提高带宽利用率
- **安全与隔离**：端口隔离、防止数据泄露
- **流量监控**：端口 MIB 统计、流量分析
- **环路保护**：防止网络环路，提升网络稳定性
- **VLAN 配置**：支持 MTU VLAN、基于端口的 VLAN、802.1Q VLAN、PVID 设置
- **QoS 配置**：基于端口、PCP、DSCP 进行流量优先级管理
- **带宽与风暴控制**：支持基于端口的带宽限制与广播风暴抑制
### 使用教程
1. **确保设备连接**
确保 NanoCluster 已上电，并通过网线将板载网口与管理主机相连。
2. **配置 IP 地址**
交换机的默认 IP 地址为 **10.10.11.10/24**，请确保管理主机的 IP 地址与其处于同一网段，例如 **10.10.11.x**（x 取值范围：1-254，且不能为 10），子网掩码设为 **255.255.255.0**。
![IP 配置](./assets/ip.jpeg)
3. **访问管理界面**
在浏览器地址栏输入 `http://10.10.11.10` 并回车，即可进入交换机的登录界面。
![登录界面](./assets/login.jpeg)
4. **登录管理系统**
在登录界面输入 **管理员账号和密码**（默认均为 `admin`），然后点击 **登录**，进入交换机管理界面首页。
![管理系统首页](./assets/homepage.jpeg)
### 基本配置
#### 端口管理
JL6108 交换机提供端口状态管理功能，支持 **端口启用/禁用**、**速率设置**、**流控管理**。
- **启用/禁用端口**：可在 **端口管理** 页面找到目标端口，选择“启用”或“禁用”
- **修改端口速率**：支持 10Mbps / 100Mbps / 1000Mbps 三种模式
- **流控**：可开启端口流控，防止数据丢失
![端口管理](./assets/portsetting.jpeg)
#### VLAN 配置
VLAN（虚拟局域网）用于划分不同的网络区域，防止广播风暴，提高网络安全性。
##### 配置端口 VLAN
1. **进入端口 VLAN 界面**
在 Web 管理界面，依次进入：`VLAN` >> `端口 VLAN`，进入 VLAN 配置页面。
2. **启用端口 VLAN 功能**
勾选 **“端口 VLAN 使能”** 选项，并点击 **`应用`** 按钮。
3. **创建 VLAN 2 并配置端口成员**
- 在 **VLAN ID** 输入框中输入 **`2`**
- 勾选 **端口 2 ~ 4**
- 点击 **`应用`** 按钮以保存配置
4. **查看端口成员表**
配置完成后，**端口 2 ~ 4 将自动从 VLAN 1 中移除**，并加入 VLAN 2。
![端口 VLAN 配置示例](./assets/vlan.jpeg)
#### QoS 配置（流量优先级）
QoS 用于保障高优先级流量（如视频会议、VoIP）的稳定性：
1. **进入“QoS 设置”**
2. 选择 **基于端口/802.1P/DSCP** 的 QoS 策略
3. 设置 **高/中/低优先级队列**
4. **保存设置**，QoS 规则生效
![QoS 配置](./assets/qos.jpeg)
### 更多配置
JL6108 交换机还支持更多高级功能，详细配置说明，请参考官方手册。
[点击此处查看完整手册](https://dl.sipeed.com/shareURL/Cluster/NanoCluster/06_Switch_JL6108)
我们提供基于 **RISC-V** 架构的 **JL6108 SDK**，用户可以从以下链接下载 SDK 并进行自主开发。
[JL6108 SDK](https://dl.sipeed.com/shareURL/Cluster/NanoCluster/06_Switch_JL6108)
## 常见问题排查（FAQ）
### 设备无法开机 / 无法进入系统
确保使用至少支持 PD 20V 输出的电源适配器，避免使用主机 USB 供电，否则可能导致设备无法正常启动。检查电源输入接口旁的绿色指示灯是否亮起，若无反应，可能是电源适配器或供电线路问题。观察每个 slot 对应的蓝色电源指示灯，判断系统是否正常启动。
如果 **LM3H** 无法进入系统，可按住 BOOT 按键后上电或复位设备，检查是否进入 UMS 模式，并通过磁盘管理确认是否识别为 U 盘。若系统损坏或无法进入，可以重新[烧录镜像](https://wiki.sipeed.com/hardware/zh/cluster/NanoCluster/use.html#烧录镜像)；若无法进入 UMS 模式，请尝试[异常刷机](https://wiki.sipeed.com/hardware/zh/cluster/NanoCluster/use.html#异常刷机（LM3H）)。
若 **CM4/CM5** 无法正常启动系统，可参考[烧录镜像](https://wiki.sipeed.com/hardware/zh/cluster/NanoCluster/use.html#烧录镜像)部分重新烧录后再进行测试。
### 网络连接异常（无法获取 IP）
如果成功进入系统但网络连接异常，无法获取 IP，请确保先插入网线再上电。交换机会在设备上电时检测网络接口，若上电后再插网线，可能导致接口无法正常识别。
### 异常刷机（LM3H）
如果因某些原因导致 U-Boot 损坏，设备无法正常进入 UMS 模式，可以通过 Fel 模式 手动恢复。使用 sunxi-fel 或 xfel 工具，将 U-Boot 加载至内存并启动 UMS 模式，然后进行刷机。
#### 进入 fel 模式
短接 slot1 的该处引脚与 GND，然后上电即可进入 FEL 模式（后续版本可能增加按键控制）。
![fel](./assets/fel.jpeg)
#### 使用 sunxi-fel
编译安装
``` bash
git clone https://github.com/linux-sunxi/sunxi-tools.git
cd sunxi-tools
make tools
sudo make install
```
烧录 U-Boot
``` bash
sudo sunxi-fel uboot /path/u-boot-sunxi-with-spl.bin
```
执行完成后，设备应能正常进入 UMS 模式，此时可继续烧录系统镜像。
#### 使用 xfel
编译安装
``` bash
sudo apt install libusb-1.0-0-dev
git clone https://github.com/xboot/xfel.git
cd xfel
make
sudo make install
```
烧录 U-Boot
``` bash
xfel ddr lpddr4
xfel write 0x4a000000 /path/u-boot-dtb.bin
xfel exec 0x4a000000
```
执行完成后，设备应能正常进入 UMS 模式，然后进行系统镜像烧录。

14
docs/hardware/zh/sidebar.yaml
View File

@@ -507,6 +507,20 @@ items:
file: kvm/NanoKVM_USB/deployment.md
- label: FAQ
file: kvm/NanoKVM_USB/faq.md
- label: Cluster
items:
- label: NanoCluster
items:
- label: 简介
file: cluster/NanoCluster/index.md
- label: 快速上手
file: cluster/NanoCluster/use.md
- label: 应用开发
items:
- label: k3s 部署
file: cluster/NanoCluster/k3s.md
- label: distcc 部署
file: cluster/NanoCluster/distcc.md
# - label: Maix Audio
# items:
# - label: MA USB 16