8.5 KiB
快速上手
修网的知识需要在实践中不断积累，网维的wiki做为每一个网维成员经验的总结，自然也需要不断的更新，但是，wiki本身大部分时间都是由开发组的仅仅几个人来维护，难以时刻更新到最新情况，所以，我们想让网维的每个人都能加入wiki的维护，这篇文章就是写给希望为wiki添砖加瓦，却不太了解相关方法的小伙伴的，希望这篇文章能够快速让你上手wiki的维护工作。 :::info 信息
在正式开始编辑前，你可以看看我们的成品网站，每篇文章的下面会有一个Edit This Page的链接，是这篇文章的源代码，这里是网站的链接：Click Me
:::
准备
我们假设你所使用的是windows系统。
首先，我们需要安装必要的开发工具：git 和 Node.js。
:::info 信息
你也可以通过windows自带的WinGet包管理器下载,详见：微软文档。
:::
:::tip git是什么？
git是一个版本控制工具，他会记录一个项目从创建之初任何人对任何文件的任何改动，大大方便了多人协作工程的管理，wiki的源代码托管在基于git设计的github上。
:::
:::tip 什么是Node.js?
Node.js是一个在后端运行javascript的运行时，我们使用基于这个平台设计的docusaurus框架来将wiki从一堆markdown文档变成一个网站。
:::
访问github,如果没有账号，就注册一个，然后，打开https://github.com/ZSCNetSupportDept/website。
点击上面的fork,创建仓库的一个分支，点击create fork。
进入你刚才fork的仓库，点击Code,选择HTTPS,复制下面的那一串内容。
然后，请打开你的终端,你可以在“开始”菜单栏里搜索"PowerShell"来打开。
如果你的系统没有安装PowerShell,你可以使用cmd，按Win+R,在弹出框里输入cmd打开。
输入git clone 你复制的内容,这将在你的当前目录下创建一个名为website的文件夹，并将开发组网站的全部内容复制到这个文件夹里面。
:::tip 提示
你可能会需要科学上网的手段来访问github。
:::
然后，输入cd website。
切换到我们的项目目录下后，运行npm install来安装项目的所有依赖。
:::tip 提示
为了加速下载，你可能会需要配置npm镜像，可以输入npm config set registry https://registry.npmmirror.com。
:::
现在，输入npm start，程序就会在你的电脑上构建并部署网站。
然后在你的浏览器上输入https://localhost:3000
如果没有出错的话，你会看到我们开发组网站的主页。
编辑
打开website下的docs文件夹，再打开wiki文件夹,这里就是我们的wiki内容仓库了。
仓库里的所有的文章都是以md结尾的markdown文件，你需要熟悉markdown的写法，才能对文章的内容修改和完善，markdown并不是特别复杂，你可以花一点时间去学会他。 :::info 信息
这里是一些学习markdown的资源：https://markdown.com.cn/
https://github.highlight.ink/mastering-markdown/intro
https://commonmark.org/ (英文)
:::
如果想要在文本中添加图片，视频，或者其他资源，请将这些素材放入static中，以方便管理。
对代码的修改将会自动同步到刚才打开的网页里，你可以在那里确认修改的结果满意与否，注意，你需要保存文件才会同步更改。
修改完毕后，输入git add .再输入git commit，并对你的修改做出一个简短的说明。
文件名
你会发现，所有文件的名字前面都有一个数字，那就是文章在sidebar中出现的顺序，增添文件，请按照order-filename.md的格式修改名字。
在文件名前加一个下划线，系统就不会将文章加入成品网站中。
推送到仓库
:::tip 提示
你可以使用github desktop或github cli来简化这个流程，不过我们想让你在这个过程中学习SSH的用法，如果你想方便一点，直接跳到“使用github-cli”。
:::
选项1:使用SSH
首先，确保你安装了SSH,你可以看微软的这片文档：链接。
打开终端，输入
ssh-keygen -t ed25519
然后在接下来的选项中检查密钥的存放路径，以及使用一个密码来加密这个密钥，我们建议你设置一个密码。
然后我们设置开机自动启动ssh-agent服务。
确保你使用了管理员权限运行了下面的PowerShell代码：
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
Get-Service ssh-agent
最后一个命令应该会返回Running状态。
然后，你就可以输入ssh-add来加载你的密钥。
ssh-add 你的私钥位置
:::tip 提示
每次重启电脑，你都要重新输入一遍ssh-add。
:::
:::info 信息
关于SSH的配置，参考了这片微软文档。
:::
接下来，我们配置github的SSH访问。
打开与私钥同目录下的公钥文件(以pub结尾)，然后复制他，注意要全部复制，不要多出或减少任何内容。
点一下你的github头像，选择Settings,然后在侧边栏的Access板块找到SSH and GPG keys。
点击 New SSH key。
把密钥粘贴到下面，然后保存就行了。
在终端里输入
ssh git@github.com
如果返回的文本里出现了你的用户名，配置就大概成功了。
现在就可以输入git push了
git push
这个命令会向远端的仓库提交你在本地提交的commit,检查你的fork仓库，有没有更新到你本地的修改？
:::info 信息
参考了github的文档:Click Me
:::
选项2：使用github-cli
访问https://github.com/cli/cli/releases ， 下载最新版本。
输入gh以检查安装的成功状况。
没问题的话，输入gh auth login,会弹出一个浏览器窗口，在弹出的窗口中完成登录。
然后，你应该就可以直接使用git push了，输入git push,然后查看你在github中的fork仓库，有没有更新到你本地的修改。
:::info 信息
这里有更多关于github cli 的信息:Click Me
:::
提交pull request
一个pull request 是一个请求，将修改建议发送给主仓库，并让主仓库合并这些修改。
打开主仓库，选择上面的Pull Requests,然后选择New Pull Request,如果没有出现你的fork仓库，点击compare accross forks。
然后就可以Create Pull Request了。
提交后，开发组成员会校对你的修改，将你的修改应用到主仓库中，这就是我们的开发流程了。
:::info wiki的分层更新模型
按照我们的设计，wiki的内容从新到旧，一共分为三个版本：
- 最新的版本是大家在自己的电脑上运行的测试版网站，这个版本包含了最新的想法和更改，等待完善后推送到主仓库。
- 然后是我们的demo版本网站zscdev-demo.pages.dev,这个版本立即反应了任何被合并进去主仓库master分支的更改，大家可以对这个网站上的内容随便提意见，任何修改都将很快被同步到网站里。
- 当主仓库和demo网站的更新积累到一定程度的数量时，开发组成员会根据一个版本作为wiki的正式版，正式推送到我们的网站developer.zsxyww.com里，这个版本通常要比demo要落后几次更新，但是那些在施工中的文章，和还在讨论的段落等不稳定的内容将不会被同步到这里，换句话说，这个版本是“稳定版”。
我们从debian的开发中(unstable/testing/stable)借鉴了这一模型,它可以确保最终正式的wiki是严谨的，可信赖的，同时将想法和讨论的场地从正式文档中分离开，确保了开发的有序进行.
这样的设计是考虑了这样的场景：有许多人同时参与wiki的开发，而不是一年不一定更新一回的随意开发，还是希望大家能多多参与到wiki的维护工作中来。。。
:::