查看“︁PX4子模块”︁的源代码

{{Note|本文档提供了PX4自动驾驶系统的Git子模块管理和镜像部署的完整指南。}}

== 概述 ==

PX4是一款开源的无人机自动驾驶系统，采用Git子模块管理复杂的依赖关系。本指南详细介绍了如何使用`--recursive`参数以及如何部署高效的PX4镜像服务。

== Git子模块与--recursive参数详解 ==

=== 什么是Git子模块？ ===
Git子模块允许将一个Git仓库作为另一个Git仓库的子目录。PX4使用这种机制来管理其依赖关系：

* '''主仓库''': PX4-Autopilot - 核心飞行控制代码
* '''子模块''': 各种依赖项目（仿真环境、通信协议、硬件驱动等）

=== --recursive参数的作用 ===
<code>--recursive</code>参数在克隆仓库时自动初始化和更新所有子模块，确保获得完整的、可立即使用的代码库。

{| class="wikitable"
|+ 克隆方式对比
! 方式 !! 命令 !! 结果
|-
| 不使用--recursive || <code>git clone https://github.com/PX4/PX4-Autopilot.git</code> || 代码不完整，无法编译
|-
| 使用--recursive || <code>git clone --recursive https://github.com/PX4/PX4-Autopilot.git</code> || 代码完整，可直接编译
|}

=== 为什么PX4需要子模块？ ===
PX4依赖许多其他开源项目：
* '''仿真环境''': Gazebo仿真器
* '''通信协议''': MAVLink通信库
* '''硬件驱动''': 各种传感器和控制器驱动
* '''算法库''': 数学计算和控制系统库

这些项目有自己的开发节奏和版本管理，使用子模块可以更好地管理这些依赖关系。

== PX4镜像部署方案 ==

=== 方案一：授权镜像方案（推荐） ===
与PX4项目团队合作，获得官方授权后建立镜像。

==== 实施步骤 ====
<syntaxhighlight lang="bash">
# 1. 获取GitHub访问令牌
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/PX4/PX4-Autopilot

# 2. 设置镜像仓库
git clone --mirror git@github.com:PX4/PX4-Autopilot.git
cd PX4-Autopilot.git

# 3. 配置定时同步（每天凌晨2点同步）
(crontab -l 2>/dev/null; echo "0 2 * * * cd /path/to/PX4-Autopilot.git && git remote update") | crontab -
</syntaxhighlight>

=== 方案二：静态资源托管 ===
仅同步发布版本和文档，不提供实时git服务。

<syntaxhighlight lang="bash">
#!/bin/bash
# 仅同步发布版本
RELEASES_URL="https://api.github.com/repos/PX4/PX4-Autopilot/releases"

# 获取最新发布信息
curl -s $RELEASES_URL | grep -o '"browser_download_url": "[^"]*"' | \
cut -d '"' -f 4 | wget -qi - -P /path/to/releases/

# 同步文档
wget --mirror --convert-links --adjust-extension --page-requisites --no-parent \
  -P /path/to/docs/ https://docs.px4.io/
</syntaxhighlight>

=== 方案三：Nginx反向代理 ===
使用Nginx反向代理将请求重定向到GitHub，同时修改响应内容中的链接。

<syntaxhighlight lang="nginx">
server {
    listen 80;
    server_name cn.px4ai.com;
    
    location /PX4/ {
        proxy_pass https://github.com/PX4/;
        proxy_set_header Host github.com;
        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 $scheme;
        
        # 修改HTML中的GitHub链接
        sub_filter 'github.com/PX4/' 'cn.px4ai.com/PX4/';
        sub_filter 'raw.githubusercontent.com' 'cn.px4ai.com/raw';
        sub_filter_once off;
        sub_filter_types text/html text/css application/javascript;
    }
}
</syntaxhighlight>

== 完整部署指南 ==

=== 环境准备 ===
<syntaxhighlight lang="bash">
# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装必要软件
sudo apt install -y nginx git curl wget

# 创建项目目录
sudo mkdir -p /opt/px4-mirror/{repos,archives,www}
sudo chown -R $USER:$USER /opt/px4-mirror
</syntaxhighlight>

=== 下载PX4主仓库 ===
<syntaxhighlight lang="bash">
# 切换到工作目录
cd /opt/px4-mirror/repos

# 克隆PX4主仓库（使用深度克隆减少大小）
git clone --depth=1 https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot

# 初始化并更新子模块（这需要较长时间）
git submodule update --init --recursive --depth=1
</syntaxhighlight>

=== 创建压缩归档 ===
<syntaxhighlight lang="bash">
# 切换到归档目录
cd /opt/px4-mirror/archives

# 创建完整PX4压缩包（排除.git文件夹以减少大小）
tar -czf px4-autopilot-complete.tar.gz -C /opt/px4-mirror/repos/PX4-Autopilot . --exclude=.git

# 创建分块压缩包（适合大文件下载）
split -b 100M px4-autopilot-complete.tar.gz "px4-autopilot-complete.tar.gz.part."
</syntaxhighlight>

=== 配置Nginx服务 ===
<syntaxhighlight lang="nginx">
server {
    listen 80;
    server_name cn.px4ai.com;
    root /opt/px4-mirror/www;
    
    # 启用自动索引
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
    
    # 发布版本下载
    location /releases/ {
        root /opt/px4-mirror;
        autoindex on;
        
        # 设置缓存策略
        expires 6h;
        add_header Cache-Control public;
    }
    
    # 文档服务
    location /docs/ {
        root /opt/px4-mirror;
        index index.html;
    }
    
    # 重定向到文档
    location / {
        return 302 /docs/;
    }
}
</syntaxhighlight>

=== 设置自动同步 ===
<syntaxhighlight lang="bash">
#!/bin/bash
# PX4镜像同步脚本

LOG_FILE="/opt/px4-mirror/sync.log"
REPO_DIR="/opt/px4-mirror/repos/PX4-Autopilot"
ARCHIVE_DIR="/opt/px4-mirror/archives"

# 记录开始时间
echo "开始同步: $(date)" | tee -a $LOG_FILE

# 更新主仓库
cd $REPO_DIR
git pull origin main 2>&1 | tee -a $LOG_FILE

# 更新子模块
git submodule update --recursive --remote 2>&1 | tee -a $LOG_FILE

# 重新创建压缩包
cd $ARCHIVE_DIR
tar -czf px4-autopilot-complete.tar.gz -C $REPO_DIR . --exclude=.git 2>&1 | tee -a $LOG_FILE

# 创建分块压缩包
split -b 100M px4-autopilot-complete.tar.gz "px4-autopilot-complete.tar.gz.part." 2>&1 | tee -a $LOG_FILE

# 记录完成时间
echo "同步完成: $(date)" | tee -a $LOG_FILE
echo "----------------------------------------" | tee -a $LOG_FILE
</syntaxhighlight>

== 用户使用指南 ==

=== 一键下载完整PX4 ===
用户可以通过以下命令一键下载完整PX4：

<syntaxhighlight lang="bash">
# 下载完整压缩包
wget https://cn.px4ai.com/archives/px4-autopilot-complete.tar.gz

# 解压缩
tar -xzf px4-autopilot-complete.tar.gz

# 或者下载分块压缩包并合并
cat px4-autopilot-complete.tar.gz.part.* > px4-autopilot-complete.tar.gz
</syntaxhighlight>

=== 使用Git协议访问 ===
用户可以将GitHub URL替换为镜像URL：

<syntaxhighlight lang="bash">
# 原命令
git clone https://github.com/PX4/PX4-Autopilot.git

# 镜像命令（保持相同使用习惯）
git clone https://cn.px4ai.com/PX4/PX4-Autopilot.git
</syntaxhighlight>

== 常见问题与解决方案 ==

{| class="wikitable"
|+ 常见问题与解决方案
! 问题 !! 解决方案
|-
| 子模块更新失败或内容为空 || <code>git submodule deinit -f . && git submodule update --init --recursive</code>
|-
| 编译时缺少依赖文件 || 确保使用了<code>--recursive</code>参数或手动运行了子模块更新
|-
| 镜像同步延迟 || 使用多个镜像源或直接使用GitHub源
|-
| 存储空间不足 || 使用浅克隆或定期清理旧版本
|}

== 合规性建议 ==

无论选择哪种方案，请确保遵循以下合规性建议：
* 明确标注镜像来源和版权信息
* 遵循GitHub的机器人规则，设置合理的请求间隔
* 仅同步必要的资源，避免完整镜像整个GitHub
* 考虑使用GitHub官方的镜像方案（如GitHub Enterprise）
* 定期检查服务条款更新，确保合规性

== 相关页面 ==
* [[PX4仿真指南]] - 如何使用PX4进行软件在环仿真
* [[PX4硬件配置]] - 支持的飞控板和传感器
* [[PX4参数调优]] - 飞行参数调整指南
* [[Git使用指南]] - 更全面的Git版本控制教程

== 分类 ==
[[Category:PX4]]
[[Category:无人机]]
[[Category:自动驾驶系统]]
[[Category:Git]]
[[Category:开源项目]]
[[Category:软件开发]]
[[Category:镜像服务]]

{{Footer}}