企业官网建设流程全解析

最近在折腾华为云上的实验操作，尤其是基于deepseek搭建agent智能助手的场景，代码要频繁在本地和云端之间来回同步。一开始图省事，直接用网页上传文件，小项目还行，项目稍微一膨胀就麻烦得不行。后来老老实实把代码迁到了华为云的CodeHub，也就是他们家的代码托管服务，整个流程才顺起来。

这篇就写一个很实在的CodeHub保姆级教程：从零开始，怎么在5分钟内把本地代码上传到CodeHub，再把新手最容易踩的报错一次性梳理清楚。内容不挑基础，刚接触云开发的小白可以直接照着敲，已经在用Git但没用过华为云的人也能快速上手。

1. 上手前的准备：账号、工具与核心概念

1.1 华为云账号与CodeHub入口

要使用CodeHub，第一步当然是注册华为云账号。打开华为云官网，点右上角的注册，填手机号、验证码，再做实名认证。这一步别嫌烦，因为后面不管是开通CodeHub还是购买云主机，都需要一个完成认证的账号。

登录控制台后，直接在顶部搜索框输入“CodeHub”或者“代码托管”，就能找到对应服务。这里有个小提示：华为云这些年一直在整合开发工具，你进入控制台后，入口名字可能显示为“CodeArts Repo”，但功能和操作逻辑和以前的CodeHub是一脉相承的，放心用就行。

CodeHub能做什么？简单说，它就是一个放在云端的Git仓库，支持私有仓库、公开仓库，还有分支管理、合并请求、代码评审这些功能。和GitHub、Gitee比起来，它对华为云生态更友好，比如和弹性云服务器ECS、云容器引擎CCE、流水线CodeArts Pipeline都有现成的联动。对于正在做华为云相关实验、或者想把个人项目放到国内云端的开发者来说，是个很顺手的选择。

1.2 本地环境：安装Git并完成基础配置

CodeHub远程仓库管得再好，本地也得有Git这个工具才能把代码推上去。Git的安装没有难度，Windows去官网下载安装包，一路Next；macOS可以用homebrew安装，Linux直接走包管理器。

装完之后，打开终端或Git Bash，先验证一下：

git --version

能看到版本号就说明装好了。接下来务必配置用户名和邮箱，因为每次提交代码，Git都会把这两个信息写进提交记录里。不配置的话，第一次commit就会报错。

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这里有个容易忽略的点：邮箱不一定非得是华为云账号绑定的邮箱，但建议保持一致，这样CodeHub上显示提交记录时能对应到你的账号，方便追踪代码是谁写的。

1.3 理解CodeHub仓库与本地仓库的关系

很多人第一次用远程仓库会懵：本地有个项目文件夹，CodeHub网页上有个空仓库，这两者到底是怎么联系起来的？

打个比方，CodeHub上的仓库相当于公司总部的资料室，本地项目文件夹相当于你工位上的工作副本。你在工位改完文件，得“交回”资料室一份，别人才能看到；资料室里别人改过的文件，你也得“取回”本地，才不会覆盖别人的内容。

落到Git操作上，就是三件事：

• 本地项目里执行git init，把这个文件夹变成一个Git仓库；
• 用git add和git commit把文件做成一个本地提交；
• 用git push把本地提交推送到CodeHub远程仓库。

关联远程仓库时，CodeHub会给一个远程地址，类似：

https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/你的仓库名.git

这个地址就相当于是资料室的门牌号，Git靠它找到你的远程仓库。理解了这层关系，后面的操作就不会觉得每一步是孤立命令了。

2. 5分钟从零到上传：一步步手把手操作

2.1 在CodeHub创建一个空仓库

登录华为云控制台，进入代码托管服务，点击“新建仓库”。这一步有几个地方要特别注意。

第一，仓库名称。填一个和项目相关的名字，比如agent-demo，以后看起来清楚。第二，可见性。如果不希望别人随便看到，选“私有”；如果要开源，选“公开”。第三，也是最容易踩坑的地方：创建时如果本地已经有一批代码，千万别勾选“初始化仓库”或者“添加README文件”这类选项。

为什么？因为一旦CodeHub自动初始化了README，远程仓库就有了一个本地没有的提交。等你推代码时，Git会觉得远程仓库有“本地不知道的内容”，直接拒绝推送。到时候你还得先pull一次再push，白白多折腾一遍。如果是全新空白仓库，就不会有这个问题。

创建完成后，页面会显示两种远程地址：HTTPS地址和SSH地址。新手建议先用HTTPS，直接复制下来备用。我自己的习惯是，把地址复制到一个临时记事本里，免得一会儿复制错。

2.2 本地初始化仓库并关联远程地址

假设你的项目在本地路径~/projects/agent-demo，下面有main.py、requirements.txt、config等文件。打开终端，进入这个目录：

cd ~/projects/agent-demo git init

执行git init后，目录里会多出一个隐藏的.git文件夹，这就是本地Git仓库的“数据库”。接着把项目里的所有文件加入暂存区：

git add .

这一步可以用git status看一下状态，确认哪些文件会被提交。然后创建一个本地提交：

git commit -m "init project"

如果前面没配置用户名和邮箱，这一步会报错，回去执行git config --global就好。

提交完成后，关联远程仓库：

git remote add origin https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/agent-demo.git

注意，这里的origin只是远程仓库的默认名字，你叫它abc也行，但约定俗成都用origin。关联后用下面命令确认：

git remote -v

能看到fetch和push两条记录，说明关联成功了。

2.3 推送代码并验证

关联之后，推送代码：

git push -u origin main

如果你是第一次用这个方法，Git会弹出一个登录窗口，要求输入华为云的用户名和密码。这里有个大坑：密码栏通常不是你的登录密码，而是需要事先在CodeHub后台生成的“个人访问令牌”。生成位置一般在“个人设置”或“访问令牌”里，点“生成新令牌”，选择需要的权限，复制保存好。

推送成功后，终端会显示类似branch 'main' set up to track 'origin/main'的提示。回到CodeHub仓库页面，刷新一下，就能看到刚刚推上去的文件了。

以后每次改完代码，只需要三步：

git add . git commit -m "更新了什么" git push origin main

整个流程跑通后，基本就进入“本地改代码、推远程”的日常节奏了。下面专门说一下报错，因为这才是新手最耗时间的地方。

3. 为什么报错？常见问题与排查技巧实录

3.1 认证失败：Username/Password或Token错误

报错内容一般是：

remote: Auth failed fatal: Authentication failed for 'https://codehub.devcloud.cn-north-4.huaweicloud.com/...git'

这种问题九成是凭据不对。CodeHub并不直接认华为云账号的登录密码，而是要求使用“个人访问令牌”作为HTTPS推送密码。就算你密码输入正确，Git还是会认证失败。

解决办法是到CodeHub或CodeArts Repo的设置里，找到“访问令牌”，生成一个令牌。推送时用户名填华为云账号名或注册手机号，密码粘贴令牌。如果你用的是Windows，第一次认证时勾选“记住凭据”，下次就不用反复输入了。

我实际踩过的坑是：生成令牌时只勾选了“读取仓库”权限，结果push的时候报权限不足。所以生成令牌时最好把代码托管相关的读写权限都勾上，省得来回折腾。

3.2 推送被拒绝：non-fast-forward / remote contains work

报错长这样：

! [rejected] main -> main (fetch first) error: failed to push some refs to 'https://...git' hint: Updates were rejected because the remote contains work that you do not have locally.

这个情况通常就是我在2.1里提醒过的：远程仓库有本地没有的提交。比如建仓库时初始化了README，或者有同事先推了代码。

解决方法分两种情况。如果远程的提交是你不需要的，并且你是仓库唯一使用者，可以暴力覆盖：

git push -f origin main

但注意，-f是强制推送，会直接覆盖远程内容，多人协作时千万不要乱用。如果远程确实有需要保留的东西，先拉取合并：

git pull --rebase origin main

然后再push。--rebase会把你的本地提交“垫”到远程提交之后，历史更干净。如果合并时出现冲突，手动解决冲突文件后，执行：

git add . git rebase --continue

最后再push，就通了。

3.3 文件大小超限：耐心清理大文件

CodeHub对单文件大小有明确限制，一般是100MB。如果项目里不小心提交了一个很大的数据文件或模型文件，push时会报：

remote: error: File model.bin is 153 MB; this exceeds 100 MB

这种情况下，把大文件从提交中移除还不行，因为Git会把历史记录里的文件也带上，依然超限。你需要在本地彻底改写历史。

简单的做法：删除大文件后，用filter-repo或BFG工具清理历史。以git filter-repo为例：

pip install git-filter-repo git filter-repo --path model.bin --invert-paths

执行后历史里就不再有这个文件了。不过这会改变所有提交的哈希值，如果仓库已经多人共享，需要通知大家重新克隆或强制更新，所以最好在项目早期就做好约束。

更优雅的方案是使用Git LFS（Large File Storage），把大文件交给LFS管理，CodeHub也支持。但LFS有额外的流量和容量计费，个人实验项目如果不是特别缺空间，尽量避免大文件入库。

3.4 网络超时或SSL报错

有时候命令卡住半天没反应，然后报：

Failed to connect to codehub.devcloud.cn-north-4.huaweicloud.com port 443: Timed out

或者：

RPC failed; HTTP 500 curl 56 OpenSSL SSL_read: Connection was reset

这类问题大多是网络环境导致的。CodeHub的域名是华为云的国内节点，如果你所处网络到该区域的链路不稳定，就会出现超时或连接重置。

首先检查网络连通性：

ping codehub.devcloud.cn-north-4.huaweicloud.com

能ping通则说明域名解析没问题。如果丢包严重，可以尝试切换网络环境，比如从WiFi切到有线，或者换个热点。也可以调整Git的HTTP缓存大小，对偶发的大对象传输失败有缓解效果：

git config --global http.postBuffer 524288000

如果SSL握手老出错，可以临时关闭SSL验证试试，但仅限于排查问题，不建议长期开着：

git config --global http.sslVerify false

关闭SSL验证有安全风险，除非明确知道原因，否则排查完记得改回true。

3.5 中文文件名乱码与显示问题

Windows上如果直接用cmd操作，中文文件名可能显示成一串八进制转义码，看着像乱码，但push本身没问题。想让中文正常显示，执行：

git config --global core.quotepath false

另外，代码文件本身建议统一使用UTF-8编码，尤其是Python、Shell这些对编码敏感的文件。在Windows平台上我更推荐用Git Bash或Windows Terminal来跑Git命令，比cmd和PowerShell的兼容性好很多。

4. 进阶：结合华为云实验场景的代码托管实践

4.1 为什么选择CodeHub做AI Agent实验的代码仓库

这几天在做的基于deepseek搭建agent智能助手的实验，是一个典型的私有项目：里面有Python脚本、环境依赖文件、prompt模板、还有一些配置数据。代码量不大，但迭代频繁，经常要在本地改一版，再丢到云主机上跑一版。

如果每次都用网页上传，文件一多就很崩溃。把代码推送到CodeHub之后，再到云主机上执行：

git clone https://codehub.devcloud.cn-north-4.huaweicloud.com/你的用户名/agent-demo.git cd agent-demo pip install -r requirements.txt python main.py

整个过程干净利落。更关键的是，CodeHub天然就在华为云环境里，从CodeHub拉代码到云主机，走的都是华为云内网或优化链路，比从Gitee、GitHub拉代码要快不少，也不容易被网络波动打断。对经常要在云端做实验的人来说，这个优势很实在。

4.2 HTTPS与SSH两种关联方式的选择

前面一直用的HTTPS地址，优点是好理解、不需要额外配置密钥，缺点是要么每次输令牌，要么依赖凭据管理器。如果你打算长期使用一台机器干活，我更推荐配置SSH密钥，一劳永逸。

先在本地生成密钥对：

ssh-keygen -t rsa -b 4096 -C "你的邮箱"

一路回车生成在~/.ssh/id_rsa.pub。然后把公钥内容复制到CodeHub的设置页里，找到“SSH公钥”，粘贴保存。

接着修改远程地址为SSH格式：

git remote set-url origin git@codehub.devcloud.cn-north-4.huaweicloud.com:你的用户名/agent-demo.git

以后push就不用再输密码了。我个人的使用体验是：临时虚拟机或一次性实验环境用HTTPS，自己主力开发机和长期云主机用SSH，两种方式按场景切换最舒服。

4.3 分支管理与团队协作建议

单人实验项目，从头到尾用main分支没有问题。但如果是几个人一起调试agent，或者要给不同版本保留现场，分支管理就很重要了。

推荐的做法是：主分支main保持稳定可运行，新功能在独立分支开发。比如要尝试替换deepseek的prompt模板，可以：

git checkout -b feature/prompt-v2 git push -u origin feature/prompt-v2

等测试通过后，再到CodeHub上发起合并请求（Merge Request），把feature/prompt-v2合入main。这样每次改动都有迹可循，出了问题也能快速回滚。CodeHub的合并请求页面还支持代码评审，团队成员可以逐行评论，对保障代码质量很有帮助。

4.4 华为云产品配置与CodeHub的联动使用

既然已经入坑华为云，代码托管只是第一步。我在做华为云产品配置时，经常把CodeHub当成整个云上项目的“代码入口”：写好的代码推到CodeHub，然后在弹性云服务器ECS上拉下来，配合云数据库、对象存储、函数工作流一起用。

更顺滑的玩法是配置CodeArts流水线：每当向main分支推送代码，自动触发构建、测试、部署流程。比如agent项目里写好Dockerfile，推送后流水线自动构建镜像并推送到镜像仓库，云主机再拉取新镜像重启服务。这样一来，代码从提交到上线的链路就全自动了，不需要人肉在服务器上折腾。

还有个提醒：agent项目里经常会用到API Key之类的敏感信息，比如deepseek接口的密钥。不管用CodeHub还是任何远程仓库，都不要把密钥明文提交进代码里。正确做法是用环境变量、华为云凭据管理服务，或者在运行时从外部配置读取。

5. 一点个人心得与后续扩展建议

最后分享一个我实际操作中的体会。很多新手第一次接触CodeHub，最崩溃的不是Git命令本身，而是“远程仓库到底发生了什么”这件事是黑盒的。遇到推送被拒，不知道远程有什么；遇到认证失败，不知道密码到底该填什么。我的建议是，遇到报错先不要慌，把报错信息完整读一遍，再想一下本地仓库和远程仓库的差异，问题往往就清楚了一半。

还有一个非常实用的小技巧：在你自己的常用项目里，可以写一个简单的推送脚本，把git add .、git commit -m "$1"、git push origin main打包在一起，参数就是提交信息。这样日常更新代码只打一行命令就够了。不过脚本只适合单人项目，团队协作还是老老实实走标准流程。

如果你接下来也打算在华为云上做更多实验，比如基于deepseek搭建agent智能助手、部署云函数、搭建CI/CD，那CodeHub很值得花半小时熟悉起来。它不只是一个存放代码的地方，更是连接本地开发环境和华为云各类计算资源之间的桥梁。把这一环打通了，后面不管是搞产品配置还是云上计算，效率都会高出一大截。