最近在折腾华为云上的实验操作尤其是基于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去官网下载安装包一路NextmacOS可以用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 LFSLarge 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 gitcodehub.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很值得花半小时熟悉起来。它不只是一个存放代码的地方更是连接本地开发环境和华为云各类计算资源之间的桥梁。把这一环打通了后面不管是搞产品配置还是云上计算效率都会高出一大截。