diff --git a/docs/content/intro/_index.zh.md b/docs/content/intro/_index.zh.md new file mode 100644 index 00000000..a6375f74 --- /dev/null +++ b/docs/content/intro/_index.zh.md @@ -0,0 +1,17 @@ +--- +title: "介绍 Athens" +date: 2018-09-20T15:38:11-07:00 +weight: 1 +--- + +欢迎来到 Athens,Gophers!我们在[首页](/zh)上给出了一个非常简洁的 Athens 概览,因此如果你想要了解更多,那么你就来对了地方! + +本章将详细阐述 Athens 的功能,意义,以及如何在你的工作流中使用它。 + +# 下一步该去哪里 + +我们建议你从前往后阅读这个章节: + +- [Athens 101](./first-content) - Athens 的基本机制 +- [Download Protocol](./protocol) - Athens 提供 Go packages 的基本方法 +- [Components](./components) - Athens 的不同组件 diff --git a/docs/content/intro/components.zh.md b/docs/content/intro/components.zh.md new file mode 100644 index 00000000..974eab85 --- /dev/null +++ b/docs/content/intro/components.zh.md @@ -0,0 +1,25 @@ +--- +title: "组件" +date: 2018-02-11T16:57:56-05:00 +weight: 5 +--- + +从一个非常高的角度来看,系统中有三个主要的组件。 + +### 客户端 + +客户端必须是一个支持 module 的 go.编写该文档时,它是 `go1.11` + +### VCS + +VCS 对 Athens 而言是一个外部源。Athens 扫描类似 `github.com` 等的多种 VCS,并获取源。 + +### 代理 + +我们部署在企业内部的代理主要是为了: + +* 托管私有模块 +* 排除对公有模块的访问 +* 存储公有模块 + +重点在于,这个代理并不打算成为上游代理的完整镜像。对于公有模块,它的角色是为了存储并提供访问控制。 diff --git a/docs/content/intro/first-content.zh.md b/docs/content/intro/first-content.zh.md new file mode 100644 index 00000000..61c834f2 --- /dev/null +++ b/docs/content/intro/first-content.zh.md @@ -0,0 +1,13 @@ +--- +title: "Athens 101" +date: 2018-02-11T16:59:56-05:00 +weight: 2 +--- + +## 什么是 Athens? + +简而言之,Athens 是一个建立在 vgo(或 go1.11+) 之上的项目,通过它你可以更容易地处理包的依赖问题,即使在 VCS 无法访问的时候,你也可以重新构建你的项目。 + +Athens 的宏伟目标是提供一个用于存放依赖(而不是代码)的新地方。因为在 GitHub 上,每一份元数据都对应着唯一不变的代码块,所以 Athens 只需要控制原数据的存储就够了。 + +你可能已经知道“不可变”的意义,但请让我再次说明,因为这一点对整个系统是非常重要的。当小伙伴改变了他们的包,迭代,实验,或者其他的事情,代码在 Athens 中永远不会变。如果包的作者发布了一个新版本,Athens 会把它拉取下来,并展现出来。因此,如果你依赖包 M 的版本 v1.2.3,那么它在 Athens 中就永远不会改变。_即使是强制推送或者是删除版本库,这都不会改变_。 diff --git a/docs/content/intro/protocol.zh.md b/docs/content/intro/protocol.zh.md new file mode 100644 index 00000000..4a3e819d --- /dev/null +++ b/docs/content/intro/protocol.zh.md @@ -0,0 +1,77 @@ +--- +title: "下载协议" +date: 2018-02-11T16:58:56-05:00 +weight: 3 +--- + +Athens 在 Go 命令行接口的基础上建立了一些端点,用来于外部提供模块的代理通信。我们称这些端点为_下载协议_ + +vgo 在下载协议上的原始调研报告可以在这里找到:https://research.swtch.com/vgo-module + +每个端点都对应一个顶层模块。让我们假设模块 `htp` 是由 `acidburn` 编写的。 + +因此,我们下面提到的端点都假设位于 `acidburn/htp/@v/{endpoint}`(例如:`acidburn/htp/@v/list`) + +在下面的例子中,`$HOST` 和 `$PORT` 都是 Athens 服务的主机和端口的占位符。 + +## 版本列表 + +这个端点返回 Athens 中模块 `acidburn/htp` 的版本列表。下面的列表由换行符分割: + +```HTTP +GET $HOST:$PORT/github.com/acidburn/htp/@v/list +``` + +```HTML +v0.1.0 +v0.1.1 +v1.0.0 +v1.0.1 +v1.2.0 +``` + +## 版本信息 + +```HTTP +GET $HOST:$PORT/github.com/acidburn/htp/@v/v1.0.0.info +``` + +这会以 JSON 格式返回关于 v1.0.0 的信息。它看起来像: + +```json +{ + "Name": "v1.0.0", + "Short": "v1.0.0", + "Version": "v1.0.0", + "Time": "1972-07-18T12:34:56Z" +} +``` + +## 文件 Go.mod + +```HTTP +GET $HOST:$PORT/github.com/acidburn/htp/@v/v1.0.0.mod +``` + +这会返回文件 go.mod 的版本 v1.0.0.如果 $HOST:$PORT/github.com/acidburn/htp 的 `v1.0.0` 版本没有依赖, +那么响应就会像这样: + +``` +module github.com/acidburn/htp +``` + +## 模块源 + +```HTTP +GET $HOST:$PORT/github.com/acidburn/htp/@v/v1.0.0.zip +``` + +显而易见——它会把该模块的 v1.0.0 版本的源码以 zip 格式返回。 + +## Latest + +```HTTP +GET $HOST:$PORT/github.com/acidburn/htp/@latest +``` + +这个端点会返回对应模块的最新版本。如果没有 latest 标签,它会根据最后一次提交的哈希值去找到对应的版本。