GitHub开源项目复现指南

目录

前言:

一、简介

(一)GitHub

(二)Git

(三)GitBash

二、流程

1. Git 安装:

2. 本地账户设置:

3. SSH 配置:

① 检查

② 生成

③ 验证*

④ 延展 

4. 项目部署:

① 项目克隆

② 依赖项安装

③  项目运行

方式1 : 通过网页端(Web UI)运行        

 方式2:本地执行

方式3:作为python包使用 

 三、结语


前言:

        GitHub是当前的开源项目、代码分享和协作的核心平台。对于开发者来说,能够用好GitHub进行项目复现,是一项重要技能。然而,新手在尝试复现项目时会遇到各种各样的障碍,比如环境配置问题、网络连接问题等(常常复现一个项目就要花上几个小时~让人头大)。因此,本文将以一个小白的视角去介绍GitHub的项目基本复现过程,以及如何解决常见问题,作为指南供大家参考(也包括我自己)。

一、简介

(一)GitHub

        GitHub是一个基于Git的代码托管平台,广泛用于版本控制和协作开发。开发者可以通过GitHub存储、管理和分享代码,同时也能与全球的开发者进行协作。简单来说,GitHub就是一个代码仓库平台,每个人都可以在上面建立私人的或公开的代码仓库,而Git(版本控制工具)就是我们的仓库管理助手

        关于GitHub的使用,大家可以阅读该篇博客:

        github新手用法详解(建议收藏!!!)-CSDN博客

(二)Git

        Git的核心概念:仓库(Repository)、提交(Commit)、克隆(Clone)等。对于新手来说,最重要的一个概念或功能可能就是克隆(Clone)

(三)GitBash

        Git Bash是Git for Windows中自带的一个命令行工具,适用于Windows用户在Windows操作系统上使用Git命令。Git Bash提供了一个终端,用户可以在其中使用Git的常见命令(如git clone、git commit、git push等)来管理Git仓库。

二、流程

        下面我将以GitHub热门项目——ChatTTS的复现为例,介绍常见的项目复现流程。

1. Git 安装:

git的安装与配置教程-超详细版_git安装及配置教程-CSDN博客

        测试是否安装成功:快捷键(Win+R),输入 cmd,运行命令行程序。执行下列指令:

git --version

2. 本地账户设置:

        远程仓库通常支持两种身份认证方式:SSH与HTTPS协议

  • SSH协议:基于密钥对(公钥和私钥),通过机器身份进行认证。适合长期使用和自动化操作,且安全性较高。
  • HTTPS协议:基于账号和密码进行认证,适合新手和简单配置,且兼容性强,但频繁输入凭证导致便捷性较差。

        以上通过两种认证方式,用户可以在认证后获得操作仓库权限,但GitHub还需记录操作者身份信息,因此要求我们在Git上完成本地账户设置。搜索并打开Git Bash,执行下列指令:

git config --global user.name "User Name"
git config --global user.email "email@XXX.com"

git config user.name  // 查看用户名
git config user.email  // 查看用户邮箱

 

3. SSH 配置:

        SSH密钥对由公钥和私钥组成,用于远程仓库的身份认证(例如GitHub)。关于SSH密钥的相关操作(包括生成、查看、删除)如下。

① 检查

        检查本地主机是否已经存在SSH Key,若存在 id_rsa 和 id_rsa.pub文件,说明该主机已配置SSH Key,无需再次生成,直接进行 步骤 ③。

// 切换路径
cd ~/.ssh
// 查看文件列表
ls

② 生成

        若无SSH Key,则可通过在Git Bash中执行下列指令生成并查看SSH Key:

// 生成RSA密钥
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"  
// 查看公钥内容
cat ~/.ssh/id_rsa.pub
  • -t :指定密钥类型为RSA。
  • -b:指定密钥的长度,默认使用4096位的RSA密钥。
  • -C:为密钥添加注释,通常使用你的GitHub注册邮箱,以便识别该密钥。

        执行上述指令后,Git Bash会提示你输入保存密钥的路径并设置密码,但你可以不用设置,直接回车即可。私钥默认保存为:~/.ssh/id_rsa;公钥默认保存为:~/.ssh/id_rsa.pub。公钥:用户将生成的公钥上传到远程仓库平台(如GitHub)上,相当于一个“身份标识”。私钥:保留在本地计算机上,本地主机能够使用它来进行加密和解密操作。当用户尝试通过SSH协议连接远程仓库时,系统会使用你机器上的私钥进行加密,然后通过上传至远程仓库平台的公钥来验证。如果验证内容匹配,则通过身份验证。

        接下来,我们需要做的就是查看公钥内容,并将公钥“交给”远程仓库,即GitHub。具体步骤参考下列博文: 

Github配置ssh key的步骤(大白话+包含原理解释)_github生成ssh key-CSDN博客

③ 验证*

        测试用户与 GitHub 之间的 SSH 连接是否配置正确,并验证SSH 密钥是否已经成功添加到 GitHub 的账户中。在Git Bash中运行下列指令(建议提前关闭加速器):

ssh -T git@github.com

        若正确完成配置,并成功验证,会得到类似下图的输出结果:

        但经常会有宝子在该验证步骤出现报错。常见的错误有:“ ssh: connect to host github.com port 22: Connection refused或Connection timed out ”。导致这类情况的可能原因有:

  • 访问github.com的22号端口被拒

方法1:尝试切换端口至443访问github.com,需要我们修改~/.ssh目录下的config文件,将其以记事本的形式打开,改为以下内容后重新测试(ssh -T git@github.com):

Host github.com
  Hostname ssh.github.com
  Port 443

方法2:使用HTTPS协议进行访问,而非通过SSH协议。这要求我们修改~/.git目录下的config文件,需修改url属性。如下图所示:

// 改前
url = git@github.com:username/repo.git
// 改后
url = https://github.com/username/repo.git
  • 网络连接问题

        如果通过网页无法正常登录并使用GitHub的话,一般是网络问题。这种情况下,通过SSH也是无法进行访问的,此时可能需要各位小伙伴“科学上网”(不过这个我就不能教了\(^o^)/~)。

  • 域名解析出错

        如果并非上述两类问题,最有可能的就是域名解析过程出错了。关于这个问题的产生原因,参考其他博主的说法,是DNS解析出错。

        当我们在浏览器中输入 http://github.com 时,操作系统会通过 DNS(域名系统)将这个域名转换成一个 IP 地址,从而定位到实际的服务器。如果 DNS 解析出现问题,可能会导致错误的 IP 地址返回。在该类情况中,DNS 解析一般会错误地将 github.com 解析成了 localhost 的 IP 地址(通常为 127.0.0.1 或 ::1),即本地回环地址。

         如果我们使用的 DNS 服务器被错误配置或被篡改(DNS 污染),返回的 IP 地址可能不正确,当 github.com 被错误地解析为 localhost 的 IP 地址后,访问就会被发送到本机而非真正的 GitHub 服务器,也就陷入了回环,多数情况下会报错:访问超时(timed out)

        想要确定是否为该类错误,可以在Git Bash中执行下列指令(查看访问日志):

ssh -v -T git@github.com
  • 正常情况下:
$ ssh -v -T git@github.com
OpenSSH_9.9p1, OpenSSL 3.2.3 3 Sep 2024
debug1: Reading configuration data /c/Users/hjg_h/.ssh/config
debug1: /c/Users/hjg_h/.ssh/config line 1: Applying options for github.com
debug1: Reading configuration data /etc/ssh/ssh_config
debug1: Connecting to ssh.github.com [20.205.243.160] port 443.
debug1: Connection established.
  • 错误情况下:
$ ssh -v -T git@github.com
OpenSSH_9.9p1, OpenSSL 3.2.3 3 Sep 2024
debug1: Reading configuration data /c/Users/hjg_h/.ssh/config
debug1: Connecting to github.com [::1] port 22.
debug1: connect to address ::1 port 22: Connection refused
debug1: Connecting to github.com [127.0.0.1] port 22.
debug1: connect to address 127.0.0.1 port 22: Connection refused
ssh: connect to host github.com port 22: Connection refused

         如何解决上述问题呢?其实只需要让系统能够正确地解析 github.com 域名即可。方法如下:

方法1:刷新 DNS 缓存(命令行中执行:ipconfig /flushdns)

ipconfig /flushdns

方法2(推荐)修改本地Hosts文件,跳过域名解析这一步骤,使所有关于 github.com 的访问直接指向正确的 IP 地址(简单来说,就是直接告诉系统该访问哪里)

        首先,我们需要清楚 github.com 的 IP 地址是多少。在 https://www.ipaddress.com/ 上查询或直接访问:http://github.com.ipaddress.com/,即可得到自己对应的 github.com 的 IP 地址。

         或者通过向Google公共DNS服务器(8.8.8.8或8.8.4.4)发送查询请求,返回的是该DNS服务器对github.com的解析结果。在命令行中执行下述指令:

nslookup github.com 8.8.8.8

注意:GitHub的域名通常对应多个服务器IP,DNS解析结果可能会根据访问地点、时间、网络状况等因素返回不同的IP地址,因此不同的查询方式可能会得到不同的结果,选择其一即可。 

        然后,按下面这篇博客的指引修改Hosts文件,添加 github.com 域名映射

window10下用git bash下载package:能够网页访问github但是使用git bash here却无法把package下载下来_github下载不了文件 但是可以打开网址-CSDN博客

XXX.XXX.XXX.XXX github.com
eg.140.82.112.3 github.com

方法3:重新设置 DNS 服务器。在“网络和 Internet 设置”中,找到当前所使用的网络连接,修改“适配器选项”,双击“Internet 协议版本 4 (TCP/IPv4)”,选择“使用下面的 DNS 服务器地址”,并输入希望使用的 DNS 服务器地址(例如:Google 的公共 DNS~8.8.8.8/8.8.4.4)。

    ④ 延展 

    管理 SSH Key 相关操作汇总

    --生成SSH密钥对:

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

    --查看已有的SSH密钥:

    ls ~/.ssh

    --查看公钥:

    cat ~/.ssh/id_rsa.pub

     --删除SSH密钥:

    rm ~/.ssh/id_rsa ~/.ssh/id_rsa.pub

    --测试SSH连接:

    ssh -T git@github.com

    4. 项目部署:

            做了那麽多铺垫,总算可以进入正题啦!!!不过前面的步骤一定要做好,保证 ssh -T git@github.com 验证结果正确,这样能省去很多后面的麻烦,至少在 git 指令的使用上不会出现太多问题。

            本文以GitHub热门项目ChatTTS的复现为例,去介绍项目复现的基本流程。当然,不可能代表所有项目复现过程,但或多或少能帮助大家初步理解大多项目是如何部署到本地。

            首先,我们在 GitHub 网页上打开目标项目(ChatTTS)主页,可以看到下面的内容:

            文件很多,但等等再晕_(¦3」∠)_。无论是哪一个项目,一般都不会缺少 “README.md” 文件。顾名思义,就是提醒我们“阅读”它。该文件一般包含了项目简介、效果展示和使用安装说明等内容——指导用户如何使用该项目。因此,无论复现哪一个项目,都请宝子们一定要慢慢读这部分的内容,尤其是图-1中的 “Get Started” 部分(也有比较成熟的项目直接放上了 使用文档的链接,比如图2中的Fish Speech)。

    图-1
    图-2
    ① 项目克隆

            因为我们只需要复现项目,所以首先要做的就是完完整整地把别人的项目复制下来。因此,我们可以用 git clone 指令。大家可能知道在建立仓库之前,必须执行 git init ,但 git clone 实际上已经包含了 git init 这一步骤,它会自动创建一个隐藏的 .git 文件夹。

    git clone [选项] <仓库地址> [本地目录]
    
    git clone https://github.com/2noise/ChatTTS
    • git:调用 Git 程序。
    • clone:子命令,表示克隆目标仓库。
    • [选项]:可选参数,用于调整克隆行为(新手可忽略)。
    • [本地目录]:可选参数,指定克隆目标后存储在本地的目录名称。如果不指定,Git 会根据远程仓库名称自动创建一个目录。
    • <仓库地址>:远程仓库的 URL(指明克隆什么?从哪克隆?),可以是 HTTPS 格式或 SSH 格式,如下:
    eg https://github.com/username/repo.git
    eg git@github.com:username/repo.git

            理解了 git clone 的原理后,大家最初可能都会有的疑问就是——在哪执行这个指令?其实,答案很简单,在哪都可以^_^。可以是在命令行(CMD)中执行,也可以是Anaconda,还可以是git bash。原因是:终端本质上是一个命令解释器,它负责读取用户输入的命令,并调用相应的可执行程序。无论是在 Windows 的 CMD、Git Bash,还是在 Linux/macOS 的终端,只要命令(git)在系统 PATH 中都可以被调用执行。

            在执行 git clone 时需要注意的是,打开终端的位置会影响项目文件的保存位置。所以,比较在意C盘内存或是有强迫症的小伙伴,最好单独设置个文件夹保存项目,方便管理。下图中,我使用CMD在D:\~\400.Projects目录下执行了 git clone 指令(右键文件夹,点击“在终端中打开”即可,或者通过 cd 指令切换至目标路径)。

    注意:如果你正在科学上网且使用了代理,那么你需要正确配置 git 代理,否则可能会出现该类报错“ fatal: unable to access 'https://github.com/XXX/XXX/': Failed to connect to github.com port 443 after 21121 ms: Could not connect to server ” 。配置 git 代理步骤如下:

    --查看代理地址和端口:

    --配置代理: 将http://proxyserver替换为上图中的代理IP地址,port替换为端口号

    git config --global http.proxy [http://proxyserver]:[port]
    git config --global https.proxy [https://proxyserver]:[port]
    
    eg. git config --global http.proxy 127.0.0.1:7897

    --如果你未使用代理,请删除 git 代理设置:

    git config --global --unset http.proxy
    git config --global --unset https.proxy
    ② 依赖项安装

            为什么需要安装依赖项?简单地说,因为一个项目程序的运行可能也依赖其他的python库(依赖项)。开发者可能不会将依赖项上传到仓库,但我们可以通过其他渠道获取并安装依赖项。

            如上图所示, 项目开发者提供了两种安装方式:1. 直接安装、2. 通过conda安装。这两种方式有什么区别呢?

            如果采取方式1(直接安装),那么当你在CMD中执行 pip install --upgrade -r requirements.txt 时,依赖项会被安装到 全局 Python 环境 中。具体储存在:Python 安装目录下的site-packages文件夹(路径一般是:~\Python\Lib\site-packages)。

            如果采取方式2(通过conda安装),依赖项会被安装到 虚拟环境 的site-packages目录中。例如,如果使用Anaconda在base环境下安装,依赖项储存在~\Anaconda\Lib\site-packages。建议使用虚拟环境来管理项目依赖,这样可以避免不同项目之间的依赖冲突,确保环境独立性。如果你不了解什么是conda以及如何使用Anaconda管理虚拟环境,可以看我的另一篇博客:

    Anaconda用法总结&虚拟环境配置_anaconda虚拟环境-CSDN博客

    备注:如果你想知道Python环境或conda环境中安装了哪些依赖项,可以执行下列指令:

    pip list
    //pip list 只会列出当前环境中通过 pip 安装的包。
    conda list
    //conda list 列出的是当前环境中所有安装的包,包括通过 conda 和 pip 安装的包。
    
    

            具体解析下 pip install --upgrade -r requirements.txt 指令:“--upgrade”是一个可选项,表示升级已安装的包。如果指定的包已经安装,pip 会检查当前安装的版本是否与 requirements.txt 中指定的版本匹配。如果不匹配,pip 会将其升级到文件中要求的版本。“-r requirements.txt”表示要从文件“requirements.txt”中读取需要安装的包列表(依赖项和对应版本号)。注意:无论采用哪种方式安装,均需要切换至对应目录下,否则会返回无法找到目标文件的报错“ ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt' ”。如下图所示,“cd ChatTTS”指令的作用就是切换至“requirements.txt”文件存放的目录。

             方式2中,并没有选择“--upgrade”,因为新创建的虚拟环境未安装额外的依赖包,因此无需考虑版本更新问题。

    下面我将采用方式2进行安装:(注意:使用 cd <路径>,切换至先前的~\ChatTTS文件夹下)

     若正确安装,过程无报错,最终返回结果如下:

    ③  项目运行

            一个项目运行并使用的方式有很多,常见的有:1. 通过网页端(Web UI)运行;2. 本地执行Python脚本运行;3. 通过容器化(Docker)部署运行。比较成熟的项目一般会提供多种运行方式,这也是GitHub项目复现主要差异也体现在运行方式上。

            以ChatTTS为例,开发者提供了两种运行方式:网页和本地运行。从用户的角度来看,通过网页运行项目的体验感和便捷性会更好,但本地运行通常会更稳定(无需考虑网络连接问题)。但这两者都绕不开在终端执行Python脚本这一步骤。因此,仍需要在特定目录下执行指令,如下图:

    方式1 : 通过网页端(Web UI)运行        

            在Anaconda中,激活虚拟环境(chattts)后执行,下列指令:

    python examples/web/webui.py

            最终,会自动弹出下图所示网页:

    注意: 可能无法弹出网页,报错:“ ValueError: When localhost is not accessible, a shareable link must be created. Please set share=True or check your proxy settings to allow access to localhost. ”这种情况一般是因为代理设置问题,导致程序无法正常访问 localhost 。解决这个问题有多种方法,但在我尝试后,最为有效且方便的是:修改程序代码,设置 no_proxy 环境变量,使程序针对本地地址的请求绕过代理服务器,直接与本地服务器建立连接。

    import os
    os.environ["no_proxy"] = "localhost,127.0.0.1,::1"

    以记事本的形式打开 webui.py 文件,添加上述代码内容,如下图所示:

     虽然,网上还有其他解决方式,例如:修改或添加demo.launch(share=True)在终端中执行export no_proxy="localhost,127.0.0.1,::1"关闭代理服务器……但基本没效果或者不方便后续使用o(╥﹏╥)o。

     方式2:本地执行

            不得不吐槽下,ChatTTS提供的本地执行示例真的很简陋(没说怎么调参、没有演示视频、没有不同功能的执行示例),或许它的官方网站 chattts.com 上可能有说明吧(但我没找到)。基本流程和方式1类似,也是执行python脚本,但此时需要用户同时输入生成内容,如下:

    cd D:<路径>\ChatTTS
    conda activate ChatTTS
    python examples/cmd/run.py "Your text 1(对话内容1)" "Your text 2(对话内容2)"

            在 Python 中,如果你需要在命令行传递参数给脚本(run.py),通常使用 sys.argv 或 argparse 来接收这些参数。因此,在上述指令中需要输入 "Your text 1(对话内容1)" "Your text 2(对话内容2)",用于生成音频。

            生成的音频文件保存在ChatTTS目录下,文件名格式为:output_audio_[数字].mp3。

    方式3:作为python包使用 

            用户直接从 Git 仓库安装 Python 包或模块。安装时,pip 会查找仓库中的 setup.py 或 pyproject.toml 文件,作为安装指示。安装后,该Python包可以在Python脚本中导入并使用。

            该方式适合需要快速安装和将 GitHub 项目作为包应用于其他项目的情况,本文中不再过多介绍。 

     三、结语

            其实,对于曾经也是小白的我来说,初次接触GitHub也是有些畏惧和排斥,因为大多项目开发者都默认使用者有一定基础,因此许多项目说明都是“言简意赅”,对于小白的确不友好。但谁又没有经历过小白这一阶段呢(#^.^#)。

            是小白没关系,但不能只是从表面去认识代码和指令,慢慢地理清各类工具之间的关系,了解指令背后的深层机制,明确报错的产生原因,而不要只为了解决问题。慢慢做,细细想,第一次复现可能会花很长时间,但这之后再次遇到相似的问题,你也许就能独自去尝试解决。具体问题具体分析,网络上的方案不一定有效,一个个试不如思考后择优尝试。

            写下这篇博客,不仅是给我自己看,也是希望大家能在学习的开始少走些弯路。CSDN上关于这方面的文章确实不多,主要是项目千奇百怪,确实没有一个范式去说明复现流程。我所能做的也只有根据自己的经验和理解,去总结些常用方法,记录些常见报错,希望能帮到大家\(^o^)/~。

            本文的部分内容来自我个人的主观思考,如有错误或不严谨的地方也欢迎大家评论区指出!

    评论
    添加红包

    请填写红包祝福语或标题

    红包个数最小为10个

    红包金额最低5元

    当前余额3.43前往充值 >
    需支付:10.00
    成就一亿技术人!
    领取后你会自动成为博主和红包主的粉丝 规则
    hope_wisdom
    发出的红包
    实付
    使用余额支付
    点击重新获取
    扫码支付
    钱包余额 0

    抵扣说明:

    1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
    2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

    余额充值