本文基于我自己的摸索，实现思路来源于RaspAP，我实际用下来RaspAP在树莓派3B+和基于Debian 13的树莓派OS上有一些Bug，会导致任务占用100%卡死，部分功能中文翻译不佳，难以明白具体含义，而且使用网页操作调试困难，所以想手动实现。但RaspAP作为一个有图形界面且有自动化一键安装脚本的开源项目，非常值得体验。

用到的所有代码都是实测可用于树莓派3B+，根据不同的系统可能需要微调，但是整体思路互通。

应用场景：

1. 没有固定Wi-Fi或者不方便获取树莓派IP地址，需要树莓派自身广播一个Wi-Fi用于实现稳定的SSH连接。
2. 需要树莓派作为一个简易路由器，实现对现有网络的二次广播。例如，对需要身份认证的Wi-Fi通过树莓派认证联网后，再次进行广播，以实现绕过身份认证。

本指南力求讲清楚原理，而不只是让用户不断复制粘贴命令，了解原理后可根据现象自行判断、调试。

当前版本：Fix_v1

无线客户端+接入点（STA+AP）中继模式完整指南

概述

本文档详细记录了在单无线网卡设备（如树莓派3B+）上，配置其同时作为无线客户端（连接现有Wi-Fi）和接入点（广播新Wi-Fi）的完整过程与原理。此配置通常被称为“无线中继”或“热点共享”模式。

核心功能：设备通过 wlan0 连接互联网，同时通过虚拟接口 wlan1 广播一个新的Wi-Fi网络，供其他设备连接并共享互联网。

适用系统：基于Debian的Linux发行版（如Raspberry Pi OS），其他系统未测试但如果有对应的包应该都可以使用。

---

目录

1. [技术原理]
2. [前提条件与检查]
3. [逐步配置指南]
4. [故障排查与重启持久化]
5. [优化与管理]
6. [附录：配置文件摘要]
7. [更新日志]

技术原理

网络拓扑

[互联网]
    |
[主路由器/上级Wi-Fi] <--(wlan0连接)--> [本设备：树莓派]
    |                                         |
(其他家庭设备)                          (wlan1广播)
                                              |
                                  [手机/平板/电脑等其他设备]

• 上行链路 (Uplink): wlan0 接口工作在 managed（客户端）模式，通过 nmcli 连接至一个现有的Wi-Fi网络，获取互联网接入。
• 下行链路 (Downlink): wlan1 接口是创建在相同物理无线芯片 (phy0) 上的虚拟接口，工作在 AP（接入点）模式，由 hostapd 服务管理，广播一个新的SSID供其他设备连接。
• 路由与地址转换 (NAT): 内核的 IP转发 功能被启用，配合 iptables 的 MASQUERADE 规则，将来自 192.168.4.0/24（AP网络，此IP可自定义）的流量进行源地址转换，使其看起来是从 wlan0 的IP发出的，从而实现共享上网。

关键概念

• 虚拟无线接口：部分现代无线网卡（如树莓派3B+所用的BCM43455）支持创建多个“虚拟”接口，每个可独立运行在不同模式。
• 并发模式：网卡需支持在同一个频段（如2.4GHz）上同时处理managed和AP模式的流量。可通过 iw list 命令检查 Supported interface modes 项。
• 网络桥接 vs NAT：本文采用NAT方式，优点是配置简单，且能将客户端设备与上级网络隔离，安全性较好。桥接方式则需要上级网络支持，且客户端与上级设备在同一广播域。

前提条件与检查

1. 操作系统：已安装Raspberry Pi OS（测试使用Debian 13）或类似Debian系统。
2. 网络连接：设备已能通过有线或无线方式连接互联网，以便安装软件包。
3. 硬件支持：已验证无线网卡支持AP和虚拟接口。

# 检查是否支持AP模式
sudo iw list | grep -A 10 “Supported interface modes”
# 输出应包含 “AP” 和 “managed”
    
# 检查当前接口状态
sudo iw dev
# 确认 wlan0 已存在

逐步配置指南

第1步：安装必要软件包

sudo apt update
sudo apt install -y hostapd dnsmasq iptables-persistent
# hostapd: 提供AP功能，广播热点
# dnsmasq: 提供DHCP和DNS服务，分配IP地址
# iptables-persistent: 保存防火墙规则

第2步：创建并配置虚拟AP接口 (wlan1)

# 创建虚拟接口，类型为 __ap
sudo iw dev wlan0 interface add wlan1 type __ap

# 再次设置接口类型为AP并启用
sudo ip link set wlan1 down
sudo iw dev wlan1 set type __ap
sudo ip link set wlan1 up

# 为AP接口分配静态IP（作为局域网的网关）
sudo ip addr add 192.168.4.1/24 dev wlan1

第3步：配置hostapd（Wi-Fi热点）

创建配置文件 /etc/hostapd/hostapd.conf：

sudo tee /etc/hostapd/hostapd.conf > /dev/null << EOF
interface=wlan1
driver=nl80211
ssid=MyRaspberryPiAP  # 请更改为您的热点名称
hw_mode=g             # 使用2.4GHz频段（a=5GHz）
channel=6             # 建议使用1, 6, 11中干扰较小的
wmm_enabled=0
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=StrongPass123  # 请更改为强密码
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP
EOF

# 指定hostapd使用我们的配置文件
echo ‘DAEMON_CONF=“/etc/hostapd/hostapd.conf”’ | sudo tee -a /etc/default/hostapd

# 启用并启动hostapd服务
sudo systemctl unmask hostapd
sudo systemctl enable hostapd
sudo systemctl start hostapd

第4步：配置dnsmasq（DHCP服务器）

为了避免与系统原有的dnsmasq配置冲突，我们使用独立配置文件：

sudo tee /etc/dnsmasq.d/raspap-dhcp.conf > /dev/null << EOF
# 仅监听AP接口
interface=wlan1
# DHCP地址池范围
dhcp-range=192.168.4.100,192.168.4.200,255.255.255.0,24h
# 指定网关和DNS服务器
dhcp-option=3,192.168.4.1
dhcp-option=6,192.168.4.1
# 日志记录（可选）
log-dhcp
EOF

# 重启dnsmasq服务
sudo systemctl enable dnsmasq
sudo systemctl restart dnsmasq

第5步：配置IP转发与防火墙规则（NAT）

# 1. 启用内核IP转发（临时生效）
sudo sh -c “echo 1 > /proc/sys/net/ipv4/ip_forward”

# 2. 设置iptables NAT规则
# “伪装”从wlan1出去，从wlan0进来的流量
sudo iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE
sudo iptables -A FORWARD -i wlan0 -o wlan1 -m state --state RELATED,ESTABLISHED -j ACCEPT
sudo iptables -A FORWARD -i wlan1 -o wlan0 -j ACCEPT

# 3. 永久保存配置
sudo netfilter-persistent save
echo “net.ipv4.ip_forward=1” | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

至此，基本配置完成。您应能搜索到新的Wi-Fi热点，连接后设备可自动获取IP，并共享树莓派 wlan0 的网络访问互联网。
请继续阅读下方关于重启持久化的内容，避免重启后功能丢失！

故障排查与重启持久化

常见问题

1. 无法搜索到AP信号

   • 检查：sudo systemctl status hostapd
   • 查看日志：sudo journalctl -u hostapd -n 50 --no-pager
   • 可能原因：wlan1接口未创建或未启用；hostapd配置错误；信道不合法。
   • 服务启动异常：启动脚本卡在等待wlan0接口UP，请检查raspap-bridge日志确认。

2. 能连接AP但无法获取IP

   • 检查：sudo systemctl status dnsmasq
   • 查看租约：cat /var/lib/misc/dnsmasq.leases
   • 可能原因：dnsmasq未正确监听 wlan1；防火墙阻止了DHCP请求。

3. 能获取IP但无法上网

   • 检查：sudo sysctl net.ipv4.ip_forward (必须为1)
   • 检查：sudo iptables -t nat -L POSTROUTING -v -n (查看MASQUERADE规则)
   • 可能原因：IP转发未开启；iptables NAT规则丢失；树莓派自身 wlan0 无网络。

解决重启失效问题（重启持久化）

系统重启后，手动创建的 wlan1 接口和临时防火墙设置会丢失。我们需要创建一个 systemd服务 来自动化这一过程。

1. 创建启动脚本 (/usr/local/bin/raspap-bridge-start.sh)：

#!/bin/bash
# 增强版启动脚本：创建AP接口并确保IP转发开启
# Fix_v1: 修复在未连接wlan0的时候卡死；并确保操作wlan1的时候wlan0停止工作

# 确保无论脚本如何退出，都将 wlan0 恢复为 UP
trap 'ip link set wlan0 up 2>/dev/null' EXIT

# 1. 等待 wlan0 接口出现（无论状态）
echo "正在等待 wlan0 接口出现..."
timeout=60
while [ $timeout -gt 0 ]; do
    if ip link show wlan0 >/dev/null 2>&1; then
        echo "wlan0 接口已存在。"
        break
    fi
    sleep 1
    ((timeout--))
done

if [ $timeout -eq 0 ]; then
    echo "错误：等待 wlan0 接口超时，退出。"
    exit 1
fi

# 2. 临时禁用 wlan0 的连接，并断开已有连接（避免干扰）
echo "临时禁用 wlan0 连接并断开..."
ip link set wlan0 down
nmcli device disconnect wlan0 2>/dev/null # 如果有连接就断开，忽略错误

# 3. 创建虚拟AP接口 wlan1
echo "正在创建虚拟AP接口 wlan1..."
# 如果之前存在 wlan1，先删除（避免冲突）
iw dev wlan1 del 2>/dev/null
iw dev wlan0 interface add wlan1 type __ap 2>/dev/null
ip link set wlan1 down
iw dev wlan1 set type __ap
ip link set wlan1 up
ip addr add 192.168.4.1/24 dev wlan1
echo "接口 wlan1 配置完成。"

# 4. 强制开启内核IP转发
echo "正在启用内核IP转发..."
echo 1 > /proc/sys/net/ipv4/ip_forward
# 同时确保永久配置文件中存在该设置（双重保险）
sed -i '/^net.ipv4.ip_forward/d' /etc/sysctl.conf
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf

# 5. 恢复 wlan0 为 up
echo "恢复 wlan0 连接..."
ip link set wlan0 up

echo "RaspAP桥接服务启动完成。"

2. 创建systemd服务单元 (/etc/systemd/system/raspap-bridge.service)：

[Unit]
Description=RaspAP Bridge Service (Creates wlan1 and Enables IP Forwarding)
# 在网络完全就绪后启动，并必须在 hostapd 和 dnsmasq 之前
After=network-online.target
Wants=network-online.target
Before=hostapd.service dnsmasq.service

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/raspap-bridge-start.sh
# 停止时清理接口（可选）
ExecStop=/sbin/iw dev wlan1 del 2>/dev/null || true

[Install]
WantedBy=multi-user.target

3. 配置依赖并启用：

sudo systemctl daemon-reload
sudo systemctl enable raspap-bridge.service
# 让hostapd明确依赖此服务
sudo systemctl edit hostapd.service

在打开的编辑器中添加：

[Unit]
Requires=raspap-bridge.service
After=raspap-bridge.service

4. （可选）防止NetworkManager干扰：

echo -e ‘\n[keyfile]\nunmanaged-devices=interface-name:wlan1’ | sudo tee -a /etc/NetworkManager/NetworkManager.conf
sudo systemctl restart NetworkManager

5. （可选）禁用 dhcpcd 以避免冲突
   如果你的系统同时使用 dhcpcd 和 NetworkManager 管理网络，建议禁用 dhcpcd 以避免冲突。

sudo systemctl disable dhcpcd --now

优化与管理

性能与安全优化

1. 信道选择：使用 sudo iwlist wlan0 scan | grep Channel 查看周围信道占用，将 hostapd.conf 中的 channel 设置为最空闲的信道（如1, 6, 11），避免与 wlan0 所连网络同信道。
2. 密码与加密：务必使用强WPA2密码，并考虑定期更换。
3. 客户端隔离：如需防止客户端间互相访问，可在 hostapd.conf 中添加 ap_isolate=1。

常用管理命令

# 查看服务状态
sudo systemctl status raspap-bridge hostapd dnsmasq

# 查看已连接的客户端
sudo iw dev wlan1 station dump

# 查看DHCP分配的租约
cat /var/lib/misc/dnsmasq.leases

# 实时查看hostapd日志
sudo journalctl -u hostapd -f

# 一键停止热点（保留wlan0连接）
sudo systemctl stop hostapd dnsmasq
sudo iw dev wlan1 del

# 一键启动热点
sudo systemctl start raspap-bridge hostapd dnsmasq

创建状态检查脚本

/usr/local/bin/check-ap-status：

#!/bin/bash
echo "=== RaspAP 无线中继状态检查 ==="
echo ""
echo "1. 服务状态:"
systemctl is-active raspap-bridge.service hostapd.service dnsmasq.service | while read s; do echo "  - $s"; done
echo ""
echo "2. 网络接口:"
iw dev | grep -A 1 "Interface wlan"
echo ""
echo "3. IP转发:"
sysctl net.ipv4.ip_forward
echo ""
echo "4. DHCP租约 (最近):"
tail -n 5 /var/lib/misc/dnsmasq.leases 2>/dev/null || echo "  暂无租约记录"

运行 sudo chmod +x /usr/local/bin/check-ap-status 后即可使用。

附录：配置文件摘要

组件	配置文件	核心参数	作用
hostapd	/etc/hostapd/hostapd.conf	interface=wlan1, ssid, wpa_passphrase, channel	定义热点的SSID、密码、信道等
dnsmasq	/etc/dnsmasq.d/raspap-dhcp.conf	interface=wlan1, dhcp-range=...	为连接的设备提供IP地址
Systemd	/etc/systemd/system/raspap-bridge.service	After=..., Before=..., ExecStart=...	定义启动顺序和要执行的脚本
启动脚本	/usr/local/bin/raspap-bridge-start.sh	创建接口、启用转发	在启动时初始化网络环境
内核参数	/etc/sysctl.conf	net.ipv4.ip_forward=1	永久启用IP转发功能
防火墙规则	/etc/iptables/rules.v4	POSTROUTING -o wlan0 -j MASQUERADE	永久保存NAT规则

重要提醒：修改任何配置文件后，通常需要重启对应的服务（如 sudo systemctl restart hostapd）才能使更改生效。

更新日志

Fix_v1 (2026-03-23)

• 修复：启动时因等待 wlan0 接口 UP 导致 AP 无法广播的问题。
• 改进：修改 /usr/local/bin/raspap-bridge-start.sh，仅等待接口存在，先关闭 wlan0 再创建 wlan1，最后恢复 wlan0，确保 AP 优先建立且不依赖上行连接。
• 增强：添加 trap 确保脚本退出时恢复 wlan0 状态。
• 优化：禁用 dhcpcd（由 NetworkManager 管理网络），消除启动冲突。

---

本指南记录了从原理到实践，从功能实现到持久化稳定的完整过程。希望它能帮助您和他人顺利地搭建稳定的无线中继网络。