Blog by Jonathan Dai

轻量级健身综合入门指引

Mon, 26 Sep 2022 02:02:22 GMT

1. 前言
2. 目标
- 2.1 目标分类/衡量
- 2.2 目标设定
3. 知识与原理
5. 如何开始
6. 如何居家训练

1. 前言

开始健身也有点年头了，从一开始的纯有氧，到后来基本上纯力量，知识经验积累都不少，这里做点总结，也分享给一众友人。

2. 目标

健身之前，首先需要明确自己健身的目标是什么。所谓give and take，健身无论从物质还是精神上，都是一项相当高付出的活动，所以还是有必要给自己设定目标并有针对性地进行训练。每个人的需求各不相同，达成目标的手法也不同，所以了解训练和目标的类型是有必要的。

2.1 目标分类/衡量

一般常见的健身目标有：

增肌
减脂
心肺强化

几点概念：

增肌
- 增肌不仅仅只是为了增肌，骨骼肌是人体热量消耗最大的部位之一，增肌能显著增加热量消耗也就是减脂
- 要做可持续的减脂都必需先增肌（总是有人喜欢靠少吃减少摄入，或做大训练量的有氧运动来减脂，但这种做法很难保持，经常会反弹）
减脂
- 极限减脂和增肌是相冲突的，极限减脂的时候会严格控制摄入量以造成热量缺口，对肌肉的生长是有影响的
心肺功能
- 极限增肌和有氧训练是冲突的，过多的有氧训练会导致人体的代谢水平激增能量物质消耗增大，自噬等消耗蛋白质的反应会激增，且肌肉容易过度疲劳而无法更好成长，所以一般增肌为主的话，有氧的量会减少
- 一般单次训练的时长需要控制在1小时以内，这样生长激素以及神经刺激等都是最好的
- 比较专业的训练一般很轻松就能达到40分钟以上，如果再加上有氧就太长了
- 当增肌走到一个更高的极限的时候，有氧或者说心肺功能会是一个阻力点，所以即便是增肌，平时有氧训练也是不能少的，一般一周1-2次，或者一周多次但和阻抗训练分开
平衡
- 从上面的几点可以看出，各个目标之间有的时候是相互冲突的，关键在于掌握好平衡

对普通人来说，综合训练是最合适的，一定量的增肌训练，一定量的HIIT促进减脂，再加一点持续时间有点长的有氧。不要求非常显著的训练效果，以保持身体健康为第一目标。

一般来说虽然不需要以极限增肌为目标，但无论如何日常的训练目标里应该加入一定量的阻抗训练以维持人体的肌肉量。

目标的度量：增肌

最大力量：比如说卧推或硬拉能上xxKG
肌肉维度：自己测量臂围、胸围、臀围等

目标的度量：减脂

体重/BMI：最粗的衡量指标，而且不太能作为依据来参考，如果在没有体脂率测量工具的情况下可以作为最基本的衡量标的
体脂率：减脂的唯一真正目标，一般家用的体脂秤能看个大概/趋势，数值细节就不用多看了，一般不准

目标的度量：心肺功能

心率：同样强度（比如说跑步配速）的情况下，观察心率的变化就能很好衡量有氧能力的进步
最大摄氧量：最科学的目标，但是一般没设备，所以了解下就好

2.2 目标设定

了解了目标的分类和衡量标准之后，接下来就是根据自己的情况和需求来选择对应的目标。先决定目标类型，然后再制作短期的目标。在制作目标的时候务必设定可以达到的目标。

错误的例子：

增肌：「我要练出XXX那样的肌肉」；不可能
减脂：「1个月里我要减掉xx%的脂肪」；做不到

正确的例子：

下个月我卧推的最大重量要增加4KG
下个月我体重需要减掉1KG

设定做不到的目标将会非常严重挫伤积极性，一开始尽量要保证正向的激励（可完成），并保证坚持。只要能坚持，其他什么都好说。

有一句话相当有道理：健身是一种生活状态，而不是一个目标。短期来说，健身设定目标是有必要的，但从长远来说，健身是一种必须长期持续的状态，目标感就很淡了，更多的是坚持下去的大目标。就像你买车开车，定期要做检查更换零件，你不会觉得买车第一年做个检查就够了后续就再也不需要了吧？一样的道理。

本文剩下的篇幅会集中在阻抗训练上。刚才也说到了，减脂就是阻抗训练+少吃，有氧一般不需要很专业的指导。实际上，健身最重要就的在于阻抗训练/力量训练。

3. 知识与原理

从这节开始我会讲相当多的健身知识和原理，会非常枯燥，但对于真正理解健身的人来说，这节才是真正的宝库。就像你去解一道数学问题的时候首先你需要学会公式，否则怎么解都不知道。一样的道理，阻抗训练里有相当多的知识点，不知道的话那就只能说是在胡乱训练罢了，非但不容易得到效果，还容易受伤。

3.1 RM - repetition maximum

在我们开始任何之后的解说之前，我们先要解决2个问题：

如何度量个人的力量（以便为后面的训练应该使用多少重量进行指引）
- 没有确定的方法来度量个人的力量就没办法了解应该使用什么重量进行训练，过重会受伤，过轻就没效果
如何确定训练的重量
- 和第一点提到的是一个点，不过这里还要提一下就是关于沟通的统一标准
- 多人之间的沟通（或者我们不说沟通，就说个人在单独学习健身知识的时候）应该以统一的标准进行，就比如说KG
- 但即便重量一致，每个人在同样重量下的表现和训练效果是不一致的，这里RM就起作用了

RM是：在某个重量下，一个人能将动作重复进行的最高次数。所以RM是一个相对的数值，是用来度量训练负荷的数值。

为什么说相对，因为每个人RM10的训练重量是完全不同的。大神的RM10（10次力竭）可能是100公斤，新手的RM10可能是10公斤。重点在于个人在某个重量下的最高可重复次数。
为什么说这是用来度量训练负荷的数值，是因为虽然重量每个人不同，但结果都是一样的，都是重复X次之后力竭，再也做不了下一个了。也就是说训练效果是一致的。

3.2 RM与训练效果

肌肉训练的三个维度：

最大力量
肌肉维度
肌肉耐力

训练的时候不可三者兼得，所以需要取舍。RM不同的动作对于这三个维度的刺激是不同的：

RM值越低的训练越代表倾向于纯粹的力量（最大力量的提升），一般新手要训练力量的话，3-5的重量是比较合适的，尽量避免1左右的训练，风险太高容易受伤
RM值8-12都是我们平时说的增肌比较合适的范围，比较均衡，更适合进行肌肥大训练（外观、肌肉维度）
RM值高于15一般就没有训练意义了，更偏向于肌耐力，一般可以作为单次训练结束的收尾加量

新手更推荐使用RM12的量来进行训练，但要保证姿势正确且真的是力竭了，也就是说12个之后，无论如何也做不了第13个了。

高手一般会在单次训练中兼顾第一和第二种情况，也就是说即有低RM的力量训练，也有高RM（一般不高于10，除非是小肌群）的维度训练。

3.3 单部位训练的多种动作

新手肯定会有一个问题，那就是为什么我练一块肌肉（一个部位），需要换那么多动作。

这是因为我们的肌肉是通过肌腱连接在骨骼上的，通过不同的姿势和不同的动作，肌肉的运动范围是不同的（也就是经常说的激活）。即便是针对同一块肌肉，不同的动作可以产生不同的运动范围，也就能得到不同的刺激。

举个例子：

手臂的三头肌有3个头，长头、外侧头以及内侧头，不同的动作因为起始的位置不同，肌腱和肌肉的伸展是不同的，那么其在运动的过程中，针对不同的头的刺激也是稍有不同的。我们在训练的时候就会多走几个动作，以期能顺利刺激到三头肌的不同部位。

颈后位的三头肌动作，三头肌的长头在初始的位置就已经是充分拉伸了，所以刺激效果会非常好。

3.4 重复次数与组数的意义

我们常说训练的时候要做某个动作N次（之前也说过了，RM10就是10次力竭）算一组，然后重复地做好几组才算是一个动作训练完成。那么为什么我们需要针对同一个动作做好几组呢？

这是因为肌肉是一个束，其内部是由大量的肌肉细胞组成的，每次我们训练的时候，只训练一个组就结束的话，是无法把所有的肌肉细胞都尽可能地刺激到的。所以我们会针对一个相同的动作做好几组，尽量把该肌肉束中的肌肉细胞全部都刺激到。这样才能尽可能地促进该肌肉成长。

至于是不是越多越好，那当然也不是，万事都要讲究一个度。之前也提到过，总的训练时长要尽量控制在1个小时之内，而且不同的动作也要尽量兼顾到，不能在一个动作上重复过多的组数。

3.5 DOMS - 延迟性肌肉酸痛

DOMS即Delayed onset muscle soreness，平时我们不是在健身的场合也会遇到过，比如说搬家搬重物的时候，如果用力过猛或者时间过长的话，第二天肌肉总是会超级痛，这就是DOMS。

在健身的时候这种情况会像吃饭喝水一样正常，这也是衡量训练效果的一个非常重要的信号。一般来说，如果训练到位了，针对目标肌肉的刺激足够的话，第二天开始DOMS是必然会出现的。反过来说，如果没有DOMS，那说明你的训练还不够。或者说你的训练有问题，没有刺激到目标肌群。

不过也不需要太过害怕DOMS，一般来说除了腿之外，其他部位的DOMS是不会影响正常生活的。

（真的不是开玩笑）

不过要注意DOMS会显著降低肌肉的能力，包括神经的募集能力，所以在DOMS中的肌肉应该避免再次训练。否则可能效果不会太好，也更容易受伤。

这里简单聊下DOMS和一般拉伤的不同：

DOMS不影响生活，只有动到这块肌肉的时候（发生特定动作的时候）才会感觉到痛；而拉伤则是无时无刻都在痛
DOMS疼痛感不会特别剧烈，就算是动到会痛的部位也不会限制动作幅度；拉伤则会明显限制动作幅度

3.6 休息拉伸

一般训练之前和训练之后都需要进行拉伸。训练前拉伸一般和热身一起进行，保证训练过程中安全不受伤。训练后的拉伸有助于后续的肌肉恢复，并提升训练效果。总之不要偷懒好好拉伸就对了，特别是训练后的那部分。

3.7 训练周期

大肌群的训练需要72小时才能恢复，包括神经的募集能力，所以一般大肌群一周一练就足够了
小肌群可以穿插在大肌群之间进行，这样能更好延长大肌群的神经疲劳恢复时间
短时间内针对某一肌群反复训练反而会有反效果，训练的目的是为了刺激肌肉生长，过多的训练反而不利肌肉恢复和生长
普通人一周的训练可以按：胸、背、二头、三头、肩部+腹部、臀腿，再加一次长时间的有氧，正好7天

3.8 神经的募集

人体动作的进行是由大脑发出信号，经过神经系统之后传达到肌肉才得以执行的。因此肌肉的训练离不开神经的帮助。而我们在进行肌肉训练的过程中，不单单只是肌肉细胞感受到了疲劳，神经系统也是会疲劳的。特征就是即便轻量级负重的动作，做的多了后面也是会觉得力不从心或者效果不佳，这就是神经开始疲劳了。

所以我们一般说训练之后的休息和恢复也包含了神经的恢复，有的时候在负重不那么高的训练后，其实神经比肌肉更需要时间来恢复。

我们经常听到教练会说念动一致，这其实也是基于这一理论的。当你在训练的时候一直专注在自己正在训练的肌肉上的时候，神经的募集能力就更能发挥到极致。

一般大肌群的恢复需要72个小时，小肌群则需要24-48小时。

3.9 肌肉生长的理论

训练肌肉的目的是为了刺激肌肉生长，训练本身根本就不是我们的目的。所以如何让肌肉更好地生长是必须要认真思考的，否则就是管挖不管埋，开坑不埋坑。

先说结论，对于普通人来说要促进肌肉生长要做好一下几点：

早睡早起
健康饮食，30-40%碳水 + 50%蛋白质 + 10-20%脂肪
禁吸烟饮酒
每周规律的至少3-4次每次1小时左右的阻抗训练
每周2-3次每次至少30分钟的有氧训练（可以用时间更短的HIIT代替）
每次阻抗训练后及时（1小时内）补充碳水化合物提升胰岛素水平（棒棒糖之类的低量但高GI的最合适），然后及时补充蛋白质（蛋白粉补剂）

接下来简单说下原理，简单的那种：

肌肉合成需要各种激素，比如：睾酮、生长激素、胰岛素等
肌肉合成需要营养物质，比如：蛋白质、支链氨基酸、谷氨酸等
健康规律的生活习惯能很好促进激素的分泌，特别是长时间规律的分泌
酒精对睾酮分泌和肌肉合成都有极大的伤害，能避则避
胰岛素不仅仅只是用来对抗血糖的，它还是一种合成代谢用的激素，所以肌肉生长也离不开它
阻抗训练之后体内的胰岛素水平会降低，正好适合用高GI的碳水唤醒，然后就补充蛋白质，让肌肉充分生长

GI是什么？

几个链接：

3.10 识别肌肉

健身在初步入门对几个基本动作和集群有过简单训练之后，还是建议简单找点解剖学的资料来看下，了解下基本的几组常练集群的位置、大小、附着点、运动范围。这对深入学习各种健身动作，摸清训练的正确运动轨迹，以及抓肌肉的感觉很有好处。

有条件的话可以找一些解剖学的3D软件来看下：

文章最后我会有一段来简单过下所有的常练肌群。

3.11 中立位、关节锁死

中立位

指我们在训练的时候，脊柱要保证不过分前倾也不过分后倾，尽量保持在正确的中轴上，比如下图这种状态：

一旦躯干过分超前或者朝后倾斜的话，我们就说脊柱过伸或者过收了。一旦躯干保持这种状态做负重训练的话，极容易造成腰椎或颈椎受伤。特别是在做下半身的训练的时候，比如说深蹲硬拉的时候。

在训练的时候一定要有意识地保证脊柱自然中立，说人话就是这时候关节还有可运动范围，可前可后，还没完全锁死。

关节锁死

这种时候关节的单向运动性达到了极限，一旦动作不稳导致再过度受力的话，很容易受伤。一般训练的时候要有意识地不要把关节打到最大，使用肌肉的力量让关节保持仍旧有一定程度的开合性。

和上面说的中立位是异曲同工的。

3.12 向心收缩、离心收缩、等长收缩

看一张图

第一个动作是等长收缩，肌肉的体积并没有变化，长度保持不变，但这时候肌肉是在发力的，保持其位置
第二个动作是向心收缩，肌肉长度缩小，收缩发力，也是我们在日常中最常见的举起、抬起的场景
第三个动作是离心收缩，肌肉长度变长，也是我们在日常中把东西放下的场景

在健身的时候，等长收缩一般是辅助肌群的工作，他们保证躯干及动作的稳定，保证躯干没有位移。向心收缩一般大家也最熟悉，就不多说了。

主要说下离心收缩。这个名词一般人都不熟，训练的时候也常常被忽视。但对于肌肉的训练来说，其实离心收缩也是非常重要的一部分。

正确的训练步骤是：

肌肉发力收缩，向心收缩，把配重举起、抬起、压下
到达肌肉运动轨迹的顶点，保持顶峰收缩1s
肌肉发力缓慢放下配重，做离心收缩，到配重被完全放下为止

离心收缩要保证不要太快。很多人在训练的时候上去肯定是发力了的，但是放下的时候就一口气松掉了，直接像扔掉一样放掉。这样就等于训练直接少了一半的训练量，后半程完全没练到。

选择训练重量的时候也尽量要保证自己能够控制，起来的时候要稳定，放下的时候同样要稳定，不要摔杠，不要扔哑铃。如果你觉得你不能很好完成全程，那正确的选择是减少配重的重量。

3.13 动作行程

一个肌肉的可能行程是由其生理结构决定的，肌肉长度如何，附着点在哪几块骨骼上。但有的时候因为个人选择原因，我们很可能不会完整做完一个动作的全部行程。

比如说某些动作在低位的时候对关节的负担很重，那我们可能就不会跳过较低的那段行程，在下去一点之后就直接起来。再举个例子就是在极限增加最大力量的时候，我们可能会选择使用RM为3或者5之类的配重，这种情况下，动作做全程的话可能在低点就直接起不来了，所以一般也会走半程。

一般来说，行程越是完整对肌肉的刺激效果就越好。所以不是特殊情况的话，尽量选择行程完整的动作进行训练是没错的。

3.14 动作稳定性

有很多人在健身的时候会选择比较重的配重，什么姿势什么动作都要往顶格的重量上，而最后最有可能的结果就是动作变形不标准，经常化地进行借力（完成一个动作并非由本来应该训练到的肌肉部位发力，而是借用了其他部位的力量）。这样的训练是有百害而无一利的，特别是非常容易受伤。

健身训练的首要一点就是动作的稳定性。训练的时候动作必须稳定发力，上的时候可以做到慢而稳，顶峰要做到1s的收缩，放下的时候同样也需要稳，不要摔杠摔哑铃。如果能做到控制，那训练就没问题。当然事物总有例外，有的时候我们在训练最大力量的时候会用低RM的配重，会有一些动作变形，这也无可厚非，但切记这是特例，组数和次数都不会很多。总的来说，还是必须要做好控制。

3.15 多关节与单关节

健身训练一般有两种类型的动作：

多关节动作：一次训练会动到多个关节，e.g 杠铃胸推，用到了肩关节和肘关节
单关节动作：一次训练只会动到一个关节，e.g 二头肌弯举，只用到肘关节

这里的优劣利弊是：在可能的情况下尽量选择多关节动作，一般来说多关节动作有更高的上限，训练效果会相对较好，而且因为多关节动作牵涉的关节较多，训练到的肌群也较多，有更好的效率。而单关节动作则是训练后半部的补充，可以更好地对一些小肌群进行雕琢。

3.16 深层肌肉与姿势稳定性

一般我们在健身的过程中提到的肌肉都是表层肌肉，其实人身体上的肌肉远远不止只有一层，而是好几层的肌肉堆叠起来的。

下图就是背部的斜方肌，以及其下的菱形肌：

深层肌一般是用来控制人的身体姿势的，比如说你站在半圆球上是否能站得稳，是否能在站稳之后还能做深蹲。

一般我们健身是不会专门去训练深层肌的，但是深层肌对人的身体健康也是很有帮助的。所以有的时候我们可以专门做一些低负重稳定性比较差的动作，来训练。一般会用到半圆球或者瑜伽球这种提供不稳定性的道具。

3.17 坚持

开篇的时候就已经提过了，健身应该是一种生活状态，而不是一种突然想要参加的活动。也就是说，只要你还活着一天，你就应该保持运动和健身以期能维持身体的健康。既然战线那么长，减少阻力就是第一位重要的事情。

如果你真的有心要健身，就应该抛弃定势思维：

健身一定要去健身房
健身一定要请教练

我的建议是：

居家健身，保证自己没有任何藉口
自己看点健身的文章和视频，随手练几次，很快就能上手了

关于如何居家健身，后面我会有专门的篇幅来介绍。基本没多少器具就可以解决问题了。

3.18 有氧训练的选择

一般有氧在身体能负荷的情况下，应该尽量选择HIIT作为有氧的训练方式。

HIIT带有一点力量训练的特点，对肌耐力也有一定的训练效果，比纯有氧更好。而且HIIT耗时短，作为日常训练的选择优势更明显。

手机上很多APP都有专门的HIIT课程，随便选一些就行了，很容易找：

不过HIIT有一点不太好。。。蹦蹦跳跳为主（否则哪来的心率），所以老破小没法搞，楼下要上来敲门的。

3.19 常见误区

最后列几个常见误区：

女生：我不想练出肌肉
- 相信我，练出肌肉真不是这么简单的事情
重量与受伤
- 之前也提了，不要迷信大重量，首先你得有能力控制大重量
我不想做有氧，怕关节损伤
- 只要不是职业运动员级别的训练量，普通的健身训练对关节只有好处
部分减脂
- 不存在的，减脂永远是全身性的，不存在练什么部位哪里就减脂这个说法

5. 如何开始

准备工作

居家训练的准备工作我会放单独的章节。

一般训练的话，或者上健身房的话，只需要4个东西：

宽松的运动服装
一个用来摇蛋白粉的摇摇杯，记得不要买那种铁丝球是单独分离的品种，不容易弄干净，最好买一体式震荡网的那种
去海淘几桶蛋白粉，中国人的正常饮食蛋白质是肯定不够的
买1组轻量级的哑铃，在家也能补充训练一些小肌群

就这点足够了，不需要多。如果是希望能在家把训练做完做好的话，可以看我后面的专门章节。

确认合适自己的训练重量

确定自己要训练的部位
找目标部位的经典动作
找比较轻量级的负重，尝试练几次，看下这个负重是否能达到RM10
一般新手的话，一个动作能到RM10就差不多了，暂时不需要考虑低RM的力量训练

制定训练计划

每次训练都记得热身
每次练完记得拉伸
每周胸、背、二头、三头、臀腿、肩部+腰部各练一次，就6天了，然后有氧再来一天，差不多了

如何进步

当有过一阵训练经验之后，想要进一步进步的话，可以：

增加最大重量
- 在原来的重量上循序渐进增加重量
- 当新的重量也适应之后，继续增重，循环往复
增加代谢压力
- 我们按公式计算：重量10KG * 每组次数10 / 组件间隔1分钟，得到现在的训练压力是100
- 我们可以通过：增重 / 增加次数（但是尽量不要超过10，如果超过就要考虑增重） / 减少组件间隔，其中的任意组合来增加肌肉的代谢压力
- 20KG * 10 / 1 = 200
- 10KG * 12 / 1 = 120
- 10KG * 10 / 0.5 = 200
- （这里的公式/数值没有意义，我只是举个例子来说明而已）
- 调整次数和间隔之后，即便训练重量没变对于训练压力来说也是有提升的，一样能增加训练效果

一般来说，在增加代谢压力保持一阵之后，总能自然而然地增加训练重量。至少我就是这么干的。

6. 如何居家训练

还是建议任何有健身需求的小伙伴尽量一开始尝试自己在家健身，就算只是哑铃也可以，先体验下。以轻量级的训练量尽量做到坚持1个月以上。如果能做到，那再考虑下一步是健身房还是买设备。如果做不到的话，那也不用谈什么健身房买卡了，都是浪费钱。

6.1 明确目标

要能练到几个主要肌群：胸、背、二头、三头、肩、腹、臀腿
这里的练到指的不是轻量级的有练就行，而是必须有一定的负荷

6.2 设备需求

这里我会列出我现在在用的设备，以及动作和训练到的部位。

可调哑铃

重量自行判断自己的需求，我这里的是一组75KG的
每档可调范围尽量细，最好是一档2KG，我这里的是老式的一档4KG
必须是可调的，这样你在调整重量的时候可以做到10秒里解决，不要选用那种必须手动抽添哑铃片的，否则调整重量太麻烦

卧推凳

要求凳子的背部可以上下活动，主要用途：

哑铃卧推 - 胸大肌
哑铃飞鸟 - 胸大肌
站姿哑铃斜托臂弯举（40度打开椅背用来支撑肘部） - 二头
仰卧哑铃臂屈伸 - 三头
坐姿哑铃推举（90度打直座椅用来稳定支撑背部） - 三角肌

单杠

可以买那种两边有缓冲垫的单杠，安装在过道上，不需要钉子，很方便。

主要用途：

引体向上 - 背部
用来挂滑轮和钢索，可以用来完成所有向下拉的动作

弹力带

这里要注意，要买那种厚度很厚的弹力带，因为是买来用来支撑体重的，所以不是那种薄的用来拉伸的弹力带。

主要用途：

减重组引体向上 - 背部

一组滑轮钢索以及一些拉杆工具

1个滑轮 + 1根钢索，挂在单杠上
2个环扣，1个用来挂滑轮，另一个用来挂拉杆或配重
2根承重编织带，1个用来挂滑轮，另一个用来挂配重
1根双头绳，用来练三头肌
1个马鞍把手，用来练单手下拉或划船
1个V型拉力杆，用来练下压

6.3 实际安装组合效果及动作选择

这里我就综合放了，主要思路是按肌肉部位编排，每个肌肉部位：

几张解剖图
几张实际安装的居家设备图
几张动作图

6.3.1 胸部肌群

解剖图

胸大肌
三角肌前束：练胸基本上都会练到三角肌前束

设备

椅背上下调节就可以练到上斜和下斜动作。

动作

6.3.2 背部肌群

解剖图

这里会分几张来介绍

肩袖4块肌肉
- 冈上肌
- 冈下肌
- 小圆肌
- 大圆肌
三角肌后束

背部肌肉
- 斜方肌
- 斜方肌下面的菱形肌
- 背阔肌：男人的翅膀

设备

单杠 + 滑轨 + 钢索 + 弹力带

后面有两张设备图我放在动作里一起介绍

V型拉力杆
马鞍把手

动作

正握引体向上
反握引体向上
减重组参考上面的图的弹力带

直臂下拉/压

单手高位下拉

这个我在那本经典的健身书里没找到，就随便找了个gif，可以参考下。这个动作可以带一点轻微的脊柱侧弯，以达到背阔肌的最大行程和收缩。新手切记从低负荷开始尝试，保证安全并抓懂肌肉的本源感觉。

6.3.3 肱二头肌

解剖图

肱二头肌和肱肌基本上是重叠的，所以训练基本上没差，都是一起练的

设备

就是哑铃和卧推凳，其中卧推凳的用法我会在下面的动作里一并带上

动作

椅背打到40-45度，单臂手肘放上面，就可以做哑铃+卧推凳的居家版本了

6.3.4 肱三头肌

解剖图

设备

一样放动作一起

动作

6.3.5 肩部

解剖图

解剖图里没分前中后三束，我就拍了张照，分离不太好，见笑了。

设备

一样放动作一起

动作

卧推凳椅背打直，就可以用来做肩推的时候支撑背部，保证稳定性

6.3.6 腹部 + 下背

腹部一般就仰卧起坐或者悬垂抬腿就行了，不用搞太复杂，记得组间短点就行了
下背健身房可以做山羊挺身，居家就只能做做小飞燕了

6.3.7 臀腿

居家没什么很好的办法做臀腿训练，有条件还是建议上健身房。

居家基本上就只能酒杯深蹲和单腿蹲了，给两个图：

大致上就这点了

神奇的Node.js map中+=async问题

Mon, 05 Sep 2022 15:09:22 GMT

1. 看代码
2. 原理

1. 看代码

东西都不复杂，看代码就完事了，一共是4个代码片段

map 中进行 += await

const f = (x) => Promise.resolve(x);

(async () => {
  let total = 0;
  await Promise.all(
    [1, 1, 1].map(async (x, i) => {
      console.log('exec', i);
      console.log('b', total);
      total += await f(x);
      console.log('a', total);
    })
  );
  console.log('done', total);
})();

结果如图:

map 中进行 =赋值然后+=

const f = (x) => Promise.resolve(x);

(async () => {
  let total = 0;
  await Promise.all(
    [1, 1, 1].map(async (x, i) => {
      console.log('exec', i);
      console.log('b', total);
      const r = await f(x);
      total += r;
      console.log('a', total);
    })
  );
  console.log('done', total);
})();

结果如图:

map 中进行 = await +

const f = (x) => Promise.resolve(x);

(async () => {
  let total = 0;
  await Promise.all(
    [1, 1, 1].map(async (x, i) => {
      console.log('exec', i);
      console.log('b', total);
      total = await f(x) + total;
      console.log('a', total);
    })
  );
  console.log('done', total);
})();

这个结果和图2相同，也就是和上面一组相同

map 中进行同步 +=

const f = (x) => x;

(async () => {
  let total = 0;
  await Promise.all(
    [1, 1, 1].map(async (x, i) => {
      console.log('exec', i);
      console.log('b', total);
      total += f(x);
      console.log('a', total);
    })
  );
  console.log('done', total);
})();

结果如图:

2. 原理

原理一点都不复杂，稍微想一下就知道了。这里主要是要注意这种case的发生，需要有意识地规避。因为结果比较反直觉，就算是有经验的程序员也会犯错。

Git Revert Trap

Mon, 05 Sep 2022 14:09:22 GMT

1. See an example

1. See an example

Let’s see an example

Step 1. Init dir git_test and git repo

cd ~/Downloads && mkdir -p git_test && cd git_test && \
git init && \
echo 'console.log("This is init");' > index.js && \
git add . && git commit -m "init commit"

Step 2. Create branches: develop, feat-x, release

git branch develop && git checkout develop && \
echo 'console.log("This is commit in develop");' >> index.js && \
git add . && git commit -m "develop commit"

git branch feat-x && git branch release

Step 3. In branch feat-x, add one file x.js and append some codes in previous index.js, then merge it to develop

git checkout feat-x && \
echo 'console.log("code x file");' > x.js && \
echo 'console.log("feat x changes");' | cat - index.js > /tmp/out && mv /tmp/out index.js && \
git add . && git commit -m "feat: x commit" && \
git checkout develop && git merge feat-x --no-ff

Step 4. Now revert this merged commit on develop

git checkout develop && \
git revert 6aa7c6550c182605a24c95a41b7d32939f9e346f

Step 5. Go to release, make some commits

git checkout release && \
echo 'console.log("release changes1");' >> index.js && \
git add . && git commit -m "release: change1" && \
echo 'console.log("release changes2");' >> index.js && \
git add . && git commit -m "release: change2"

Step 6. Merge feat-x to release

git checkout release && git merge feat-x --no-ff

Step 7. Merge release to develop

git checkout develop && git merge release --no-ff

See the branch develop, you will find there is no changes belong to feat-x. We have this branch merged to develop previously, and we reverted that commit. Later we have commit merged from feat-x to release then release to develop. But as you can see, even this commit merged with release branch to develop later (means this commit merged to develop twice), it still not in the develop.

How to fix this:

make a new branch fix
cherry-pick the commit belongs to feat-x
merge fix to develop

git checkout develop && \
git branch fix && git checkout fix && \
git cherry-pick 6aa7c6550c182605a24c95a41b7d32939f9e346f

git checkout develop && git merge fix --no-ff

See the result:

Charles证书刷新

Wed, 15 Jun 2022 10:09:22 GMT

1. 前言
2. 几个方法
- 2.1 重置根证书
- 2.2 删除并重新生成证书

1. 前言

新版本的Charles（具体是哪个版本我不记得了）生成出来的根证书只有1年的有效期，所以很容易就会过期，导致测试使用的失败。而我上次更新根证书的时候发生了很多问题，所以这里做个笔记来记录下。

主要是参考这篇博文：Expired Charles Proxy Root Certificate

2. 几个方法

2.1 重置根证书

操作步骤：

Open Charles -> Help -> SSL Proxying -> Reset Charles Root Certificate …
Now follow the on-screen instructions
Once complete, please restart Charles

然后手机上的根证书需要删除之后重新下载安装，和之前的初始安装操作一致。

2.2 删除并重新生成证书

删除证书：

From the Keychain application, right-click the Charles Root certificate
Select delete and follow the on-screen instructions

重新生成证书：

Open Charles -> Help -> SSL Proxying -> Install Charles Root Certificate
This should now open “Keychain Access” on your Mac. Follow the on-screen instruction
Once complete, please restart Charles

老样子，手机上的根证书需要删除之后重新下载安装，和之前的初始安装操作一致。

ngrok tutorial

Fri, 15 Apr 2022 09:09:22 GMT

1. 前言
2. 安装准备
3. 使用范例

1. 前言

因为手头在做支付相关的内容，如何测试支付服务商的回调功能就比较头痛。

当年比较多的是使用自己的VPS来进行测试，代码直接ssh到VPS上就行了。但是我手头上的境外VPS都关掉了，比较贵嘛，现在blog都可以用静态服务商的免费服务，所以就没继续持有了。境内的VPS我倒是有，价格便宜，但问题在于境内VPS如果你要搭网站绑定域名的话，都要求域名经过备案，那就没辙了。

于是就需要一个能将自己的本地进程暴露到公网的方法，现在倒是有这种工具的，就比如：https://ngrok.com。

2. 安装准备

到官网上注册账号，进入console。然后到Your Authtoken页面找到你自己的token，将字符串复制下来。

接下来安装ngrok的二进制可执行文件，推荐使用brew安装

$ brew install ngrok --cask --verbose

接下来配置刚才的token，这步自己看下ngrok的版本，我用brew安装的是2.x的版本，比官网的3.x要老，所以语法有点不同

$ ngrok authtoken $your_token_string

3. 使用范例

3.1 准备本地http服务

本地生成一个静态html index文件，并使用npm的http-server启动一个本地服务器

$ mkdir -p ~/Downloads/test && cd ~/Downloads/test
$ touch index.html
$ vim index.html

<html>
<body>
<h1>test page jd</h1>
</body>
</html>

$ pwd
# /Users/jonathan/Downloads/test
$ npx http-server ./

3.2 启动ngrok

因为我们本地服务启动在8080端口上，所以ngrok的命令要以这个端口为目标

$ ngrok http 8080

3.3 测试

需要注意，每次使用ngrok命令打通tunnel都会随机分配一个域名，每次都是不一样的，所以在测试的时候记得切换代码/配置里的域名。这次测试分配到的是：211e-101-80-9-92。测试使用的时候务必记得使用https protocol，即便如此chrome还是会提醒这个网站不安全。反正只是测试用的，就无所谓了。

然后可以打开http://127.0.0.1:4040，这是ngrok的console页面，会显示访问请求列表

Swift iOS App唤起支付宝支付的简单教程

Fri, 15 Apr 2022 02:02:22 GMT

1. 前言
2. 创建iOS项目
3. 安装cocospods
4. 安装Alipay SDK
5. 桥接Alipay SDK的Header文件
6. 实现唤起Alipay

1. 前言

作为一名后端程序员，整个API链的调用联调是否能摒除所有的外部依赖是非常重要的，测试的流程贯通关系到整个开发的顺畅程度。支付系统的联调麻烦就麻烦在有外部系统的依赖。虽然在做开发的时候可以在单元测试代码中进行Mock来绕过外部的依赖，但真实的e2e测试还是必须的，这个时候就需要引入外部支付系统的接口了。

目前国内的支付系统主要就是支付宝和维信支付。微信支付有点忘记了，但支付宝的app支付和网页支付是分开的2个独立的功能，也就是说公司的app可能只签了app支付而没有签网页支付。这种情况下在测试的时候，后端下单之后就无法使用自己生成的二维码然后用手机扫码支付测试了，必须是直接在手机的app内进行测试。这就很麻烦。所以本文会做一个教程，简单教下如何创建一个简单的app，可以使用后端下单生成的返回字串来唤醒支付宝进行支付，以打通整个支付流程。

2. 创建iOS项目

首先需要注册一个Apple开发者账号，因为没有任何账号的话，是无法对App进行打包和部署到手机上进行测试的。注册去：https://developer.apple.com/，点右上角的Account，按引导注册即可。然后打开xocde，点开Perferences -> Accounts，点左下角的+添加自己的账号。

然后打开xcode，创建新项目。

题外：如果想认真学习下Swift的话，官方Tutorials教程在：SwiftUI Tutorials。此外，还有The swift programming language。

3. 安装cocospods

cocospods是iOS项目的依赖管理工具，类似nodejs的npm，基本上做项目都需要。最方便的的一点是这东西在安装的时候，会把一些对应的配置文件都更新好，对于我这样的新手来说就少了很多事情。

几篇参考：

# 安装cocospods本体
$ brew update --verbose
$ brew install cocospods --verbose
# 安装数据库，这个repo超级大，一共有将近1个GB的数据，建议用代理加速
$ git clone https://github.com/CocoaPods/Specs.git ~/.cocoapods/repos/trunk
# 完成后测试下效果，是否可以搜到dep，有结果返回就OK了
$ pod search Alamofire

4. 安装Alipay SDK

到刚才创建的新项目的根目录下，首先需要创建pod的配置文件，类似package.json

$ pod init

会生成一个Podfile，然后编辑该文件，添加Alipay SDK，添加在# Pods for AlipayTest这行下：pod 'AlipaySDK-iOS'

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'AlipayTest' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for AlipayTest
  pod 'AlipaySDK-iOS'

  target 'AlipayTestTests' do
    inherit! :search_paths
    # Pods for testing
  end

  target 'AlipayTestUITests' do
    # Pods for testing
  end

end

最后在repo的根目录下执行安装命令

$ pod install

安装完成的dep都放在：Pods/下，Alipay SDK在：/Pods/AlipaySDK-iOS。

后续需要关闭xcode，使用新生成的AlipayTest.xcworkspace文件来打开项目。

更多细节可以看支付宝官方的：客户端 iOS 集成流程。

因为Alipay SDK是使用ObjC写的，所以在Swift项目中使用需要做一步工作：引入桥接的Header文件。

执行创建文件操作，选择ObjC文件，名字随意，实际上这个ObjC文件我们后续可以直接删除，没用。IDE会问是否需要创建桥接Header，点击蓝色按钮选是，这才是我们创建ObjC文件的真正目的。

操作完成后，删除ObjC文件，打开桥接Header文件，并添加：# import <AlipaySDK/AlipaySDK.h>。

6. 实现唤起Alipay

打开创建新项目时默认生成的：ContentView。页面上添加一个 TextEditor 用来输入后端下单之后生成的sign字符串，然后一个 Button 来执行确认唤起。

要正确唤起支付宝，并能够正确支付，需要注意几个点：

进行测试的手机上需要安装好真正的业务app（我们做的支付测试app是为了测通支付流程用的，不是真正的应用app，这里说需要安装好的是我们实际接入支付的真正的业务app）
用来输入sign字符串的 TextEditor，在输入的时候需要删除之前的PlaceholderInput the sign here，我是没找到这个控件应该怎么加Placeholder…
代码中AlipaySDK.defaultService().payOrder的fromScheme需要替换成第二点中提到的真正业务app的项目名字，也就是支付宝支付完成后的回调app
- 这里不知道为什么，填写我们的测试app的名字支付宝支付会报错，具体应该和iOS应用配置打包细节有关，这个我不是专业的就不琢磨了，直接用真正的业务app的名字即可
- 所以这个支付的回调是不会走回我们的这个支付测试app的，而是会回到业务app，切记，不过无所谓，毕竟我们只是要完成支付打通支付流程而已

//
//  ContentView.swift
//  honors
//
//  Created by Jonathan Dai on 2022/4/14.
//

import SwiftUI

struct ContentView: View {
    @State var editor: String = "Input the sign here"
    @State var console: String = "Console:\n"
    
    var body: some View {
        VStack {
            SwiftUI.Group {
                Text("Pay with order sign").padding().frame(width: nil).border(Color.black, width: 2)
                TextEditor(text: $editor)
                    .padding()
                    .border(Color.black, width: 1)
                Button(action: {
                    print("Button 'Go to Alipay' clicked")
                    gotoAlipay()
                }) {
                    Text("Go to Alipay")
                }
                .padding(.all)
                TextEditor(text: $console)
                    .padding()
                    .border(Color.black, width: 1)
            }
        }
    }
    
    func gotoAlipay() {
        self.console += "gotoAlipay\n"
        print("gotoAlipay: sign: " + self.editor)
        AlipaySDK.defaultService().payOrder(self.editor, fromScheme: "YourBusinessAppNameHere", callback: { (resultDic) -> Void in
            print("Alipay reslut = \(String(describing: resultDic))");
            let resultDic = resultDic! as Dictionary
            if let resultStatus = resultDic["resultStatus"] as? String {
                if resultStatus == "9000" {
                    self.console += "支付成功\n"
                } else {
                    self.console += "支付失败\n"
                }
            }
        })
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ContentView()
        }
    }
}

UI长这样

操作：

后端下单，生成app唤起用的sign字符串
拷贝到该测试应用的第一个 TextEditor 里
点击按钮Go to Alipay
即可

Obsidian插件经验

Fri, 08 Oct 2021 02:02:22 GMT

1. 前言
2. 基础
3. 代码
4. 问题
Reference

1. 前言

之前花了点时间制作Obsidian的插件：agreatfool/obsidian-post-gallery，稍微积累了点经验，这里留点笔记。不会过于深入，因为我做的插件还是很简单的，也没有用到太多的Obsidian的功能。

丑话说在前面，Obsidian的Plugin相关文档是极其匮乏的，有很多功能你基本上找不到文档对于其的描述，更扯的是一部分概念在文档里也没解释，比如说：leaf等，导致如果你需要制作功能比较复杂的插件的话，会很困难。最好的方法就是找现在官方网站上列出来的那些community plugin的源码，然后慢慢读。我也搞不懂这些作者是怎么搞清楚那么多细节的，哎。反正我是没做很高级的功能，所以基本上没怎么接触。

2. 基础

obsidianmd/obsidian-api，算是官方的插件文档地址。这个repo里面就只有一个d.ts文件，描述了Obsidian API的内容。制作插件的时候可以使用这些官方提供的API，实际上Obsidian是基于Electron的一个封装，但官方的API并不会暴露Electron的API给你使用，是基于安全方面的考量：Security of the plugins。

obsidianmd/obsidian-sample-plugin是官方的范例repo，可以clone下来尝试下，里面有最简单的使用范例。

在编码方面，你会需要安装Obsidian API，虽然本质上它也就只是一个typing。

3. 代码

main.ts

import * as LibOs from 'os';
import { MarkdownPostProcessorContext, Plugin } from 'obsidian';
import { MarkdownBlockProcessor } from './lib/md_block';

export default class InPostGalleryPlugin extends Plugin {
  async onload(): Promise<void> {
    if (LibOs.platform() !== 'darwin') {
      console.log(`InPostGalleryPlugin.onload unsupported platform: ${LibOs.platform()}`);
      return;
    }
    console.log('InPostGalleryPlugin.onload');

    this.registerMarkdownCodeBlockProcessor('post-gallery', async (source: string, el: HTMLElement, ctx: MarkdownPostProcessorContext) => {
      await new MarkdownBlockProcessor(this.app).process(source, el, ctx);
    });
  }
}

定义一个 default export 的 class，继承 obsidian 包里的 Plugin。上面的代码就只响应了onload事件，在事件中保证插件安装在OSX系统中，并注册一个markdown代码块处理器，在post-gallery代码块出现的时候进行触发。

md_block.ts

剩下的其他功能代码也非常简单，一共没几行：md_block.ts，可以简单看下。

4. 问题

当时在制作这个插件的时候，虽然功能很简单，但还是遇到了不少问题。最主要的一个问题是代码打包。

因为所有的dep安装（源码）都是通过npm安装的，而代码的import / require又是在Obsidian (Electron)环境中运行的，所以很多用来初始化的self execute function: (function(){})()会侦测错环境，导致最终的lib加载注入错了global：global vs window。

这里需要使用第三方的打包工具来进行代码打包，比如说webpack，但因为我这个项目实在是太小了，杀鸡牛刀，也不想浪费时间搞一大堆的配置。最后就直接把一些第三方的dep的加载函数给改了下，放到src里，作为自己的源码来进行import，就行了。算是比较tricky的绕过方法。

举个例子：

原版 jquery

(function (global, factory) {
  'use strict';

  if (typeof module === 'object' && typeof module.exports === 'object') {
    // For CommonJS and CommonJS-like environments where a proper `window`
    // is present, execute the factory and get jQuery.
    // For environments that do not have a `window` with a `document`
    // (such as Node.js), expose a factory as module.exports.
    // This accentuates the need for the creation of a real `window`.
    // e.g. var jQuery = require("jquery")(window);
    // See ticket #14549 for more info.
    module.exports = global.document
      ? factory(global, true)
      : function (w) {
          if (!w.document) {
            throw new Error('jQuery requires a window with a document');
          }
          return factory(w);
        };
  } else {
    factory(global);
  }

  // Pass this if window is not defined yet
})(typeof window !== 'undefined' ? window : this, function (window, noGlobal) {
  // ...
});

修改后

(function (global, factory) {
  'use strict';

  module.exports = factory(window);

  // Pass this if window is not defined yet
})(typeof window !== 'undefined' ? window : this, function (window, noGlobal) {
  // ...
});

Reference

obsidianmd/obsidian-api
Plugins mini FAQ
Security of the plugins
Electron > API > shell
Electron > API > win.previewFile
Darakah/obsidian-gallery
Is there a way to trigger Finder’s “quick look” window with Applescript?，这个方向错了，应该搜 “electron” mac image quick look
obsidian-tools/obsidian-tools
lightGallery
justifiedGallery

Evernote: The Knowledge Database

Thu, 07 Oct 2021 02:02:22 GMT

1. 前言
2. 知识管理
3. Evernote使用
4. Evernote缺陷

1. 前言

之前在如何管理个人笔记里也提到了知识管理我选的是Evernote这款软件。这里就聊下，知识管理主要指什么，要做什么，以及Evernote这款软件的功能等。

2. 知识管理

所谓知识管理，核心功能需要以下几点：

方便简洁的知识收集能力，操作要简单，渠道覆盖要全面
基本的知识分类管理能力，按category和tag对一条知识进行组织和管理（核心是tag，category可选非必要）
强大和高效的搜索能力，1-2秒内快速搜索指定的tag对应的知识条目，需要支持复合搜索
数据导出和工具迁移能力，知识条目可以导出，并可以迁移到其他软件

即：收集、管理（标签）、搜索，三个步骤。这里编辑功能是非必要的，至少不是核心功能，编辑功能可以做得很糟糕（就比如Evernote，极其糟糕的编辑功能）。

一般的流程为：

看到合适的知识内容（微信公众号、网页等），使用Evernote的剪藏工具剪藏收集到Evernote中
更新Evernote里的剪藏post，移动到合适的category并附上合适的tags
后续如果有任何搜索需求，使用Evernote的搜索功能进行查询

3. Evernote使用

3.1 网页剪藏

剪藏的官方插件列表在这里：印象笔记剪藏·下载。Chrome插件在这里，如果是墙内的话可以自己打开前面的链接找里面的下载包。

关于如何切换国际版和国内版，参见：如何切换印象笔记国内帐户和 Evernote 国际版帐户登录入口？。

使用：点击插件列表里的Evernote图标或键盘”`“呼出剪藏面板，然后简单操作即可：

3.2 微信剪藏

官方文档：我的印象笔记@微信。按步骤操作即可。

因为很久之前的一次微信改版，现在都需要手动拷贝链接贴到微信公众号的聊天框内才能收藏，实在是很麻烦。

3.3 Tag管理

Tag的管理建议：宁滥毋缺。

因为你在使用/搜索的时候，不一定能精确记起每个你命名的tag，有的时候可以多留几个近义词来保证后续搜索的稳定性。

两个个人习惯：

为那些高质量，在搜索某个tag/概念的时候肯定想要搜到的条目附加BestPractice标签，作为后续过滤高质量条目的tag
为某些概念的条目添加CN/EN双重tag，防止某些时候想不起来：e.g DistributedSystem / 分布式系统

3.4 搜索

搜索语法参见官方文档（EN）：Search Grammar。

常用搜索：

notebook:"golang"，根据category/笔记本来搜索
tag:"TagNameXX*"，根据tag来搜索条目，搜索可以带通配符
-tag:"TagNameYY"，不包含某个tag
created:"20210704"，搜索在2021-07-04或之后创建的条目
sourceurl:"https://www.google.com/*"，根据条目url进行搜索
content，根据字符串来搜索条目内容
-content，根据条目内容搜索不带content字符串的条目
关于复合条件搜索
- 任何多条件的搜索默认都是and关系，e.g criteria1 criteria2 也就是 both criteria1 and criteria2
- 如果需要按or关系进行搜索，需要在所有的criteria之前带上any，e.g any: criteria1 criteria2

AND

4. Evernote缺陷

4.1 Editor

Evernote说实在的，在使用上还是有相当多的问题。最主要的是它的编辑能力实在是非常孱弱，基本上除了随手写点笔记之外，结构性的和系统性的文章编辑就别指望它了，任何一款主流的基于Markdown的编辑软件都比它好用。

虽然Evernote的新版本也支持markdown，但还是明显和传统笔记分割了开来，在Evernote里创建笔记只会创建出TXT笔记，而Markdown语法支持的笔记需要特定选择才可以：

4.2 Export

Evernote的导出也不是特别友好，因为刚才说的，其支持Markdown比较晚，所以大量的历史存量笔记肯定都是TXT格式（从使用者角度来说）的，所以导出的时候的选项一般只有HTML或ENEX这个Evernote专用格式（后续测试了下，即便新版本里可以创建Markdown笔记，导出的时候也只有HTML和ENEX这两个选项）。

也就是说，如果后续用户希望转到其他的平台或其他的工具，那只有祈祷转入方能够支持ENEX格式的文件了。我之前有做过一些简单research，从结果来看不太乐观，一般来说即便宣称支持的那些软件做得也不太好，会有各种各样的导入问题或展示格式问题。而且有很多软件虽然支持导入ENEX文件，但不支持批量导入，所以当你需要整个转过去的时候就基本上没办法了。

因此，使用Evernote是有壁垒的，用户要有心理准备，后续将会很难将自己的数据导出或转移到其他服务。当然这也并非Evernote一家的问题，我相信MS的OneNote应该也差不多，或者其他的软件也是如此。

4.3 Sync

Evernote还有一个问题就是同步，最早的版本会完整同步所有你账户里的数据落地到本地磁盘，但后续的更新废除了这个同步。在新版本中，每次在新的机器上进行账号登录，只会同步最近一年的数据，更早的数据不会丢失，但并不会自动下载到你本地磁盘上，而是当你点击该条目的时候，再按需从Evernote的服务器上实时下载。

这对数据完整性和数据安全敏感的用户来说极不友好，因为一旦Evernote的服务暂时不可用或永久停止服务的时候，你将没有任何手段将你的数据库完整下载下来，难道几万条条目一个个点过来吗，不现实的。

所以如果数据量不大的话，记得尽量将你目前所拥有的本地数据做好备份，比如说用好TimeMachine，保证至少有一份完整的数据存在于你本地。然后比如说当你更换新机器的时候，记得将整个本地文件夹都拷贝到新的机器上去，然后再进行账户登录和同步，这样你的本地数据就一直都是完整的了。

目前版本的Evernote在MAC上的数据存储在：

/Users/XXX/Library/Application Support/com.yinxiang.Mac/accounts/app.yinxiang.com/XXXX

$ cd ...
$ du -sh *
4.0K	ContactExtractorFetchDate.plist
4.0K	CoreNote-CheckPoint
 16K	SyncState
112K	announcements
 40K	atlas
760M	backupPreMigration
4.0K	checkpoint
  0B	chunks
 48G	content
  0B	eb-up-sell
  0B	external-edits
428K	localMessageStore
142M	localNoteStore
 11M	localNoteStore.metadata
335M	note-personal.index
203M	note.index
157M	note.index.old
8.0K	plugins
 80K	puppetmaster
 46M	purgatory
4.0K	quick-search.store
 32K	quick-search.store-shm
 12K	quick-search.store-wal
  0B	temp_relatedContent
4.0K	tierSelectionEligibility.state
265M	typeAhead-personal.index
182M	typeAhead.index
158M	typeAhead.index.old
4.0K	version

条目数据全部都存放在content文件夹下，务必保证该文件夹得到妥善的备份。

NAS备份计划及 PC备份软件推荐

Wed, 06 Oct 2021 02:02:22 GMT

1. 前言
2. SyncBackPro 介绍
备份周期和策略

1. 前言

今年上半年对家里的NAS进行了下换代。之前只有一台4 * 6T NAS，备份基本上都是使用USB零碎手工做的，效率和安全性都非常差。上半年新购了一台NAS4 * 8T。然后组装了一台Intel的集显PC（基本都是最低性能，只有主板因为需要大量SATA口，所以还算比较好）把从2004年开始装机 -> 报废循环后留下来的的大量闲置3.5寸硬盘都装了进去。

这样就：

32T新NAS作为主力机器，负责读写
24T老NAS作为备份机，备份主力NAS里的一个子集
PC差不多有33T的容量，也负责进行备份，同样备份主力NAS的一个子集
部分内容为单备，会落在老NAS或备份PC两者其一
部分比较重要的内容（e.g 十几年间的所有照片）双备，会在老NAS和备份PC中同时存在一份备份

两台NAS之间的备份比较好处理，因为都是QNAP的OS，所以直接使用系统自带的同步即可。

但是NAS到PC之间的备份就不是那么好弄了，因为Windows的SMB的关系（此处存疑，不一定就是这个原因），导致NAS到PC的备份无论是速度还是稳定性都有问题，经常容易出现半路报错退出的情况。因此找了很久替代的方案，最后锁定了今天要提的备份软件SyncBackPro。

2. SyncBackPro 介绍

主页在这里：https://www.2brightsparks.com/syncback/sbpro.html 。付费软件，将近400，因为确实做的不错，就直接下单购买了。如果不放心的话可以下载之后试用一下，不用急着下单购买。

支持的功能：

数据源备份到云盘
不同类型平台间（MAC、PC等）的数据备份
支持推送数据从本地（源）到远程（目标）
支持从远程（源）拉取数据到本地（目标）
WIN计划任务设置，自动启动计划备份
每次的备份运行都会有详细的日志，包括源与目标的文件差异，传输列表等，保证一清二楚

其他未列出的还有很多，可以说完全满足了我对于备份的要求，确实相当好用。

备份周期和策略

目前我这里每周做一次备份：

周五晚上老NAS做了电源计划任务，周五晚8点30自动启动
听到启动音，手动启动备份PC
周六凌晨，新NAS内会有同步任务，将文件从新NAS同步到老NAS
周六早晨，备份PC内会有备份任务，将文件从新NAS拉到备份PC

MAC UTM 虚拟机使用

Tue, 05 Oct 2021 02:02:22 GMT

1. 前言
2. 介绍
3. 安装
4. 文件共享
5. 端口转发

1. 前言

一般来说使用MAC操作系统都会安装一个WIN虚拟机，来协助一些需要WIN的操作。因为之前的MAC也是使用的Intel的芯片，所以可以直接在虚拟机里安装x86的WIN，这样基本上就覆盖了最经典的使用场景。

而最新的M1 MAC是ARM架构，且因为Rosetta不支持虚拟化，就导致了很多主流的虚拟机软件，类似Parallels都不支持在M1的MAC上安装x86架构的WIN10。

所以一旦有需求要使用x86的Windows，那就不能使用那些主流的虚拟机软件了，只能找一些偏门的软件。

2. 介绍

实际上可选的并不多，或者说最后我就只找到了QEMU，而在其基础上进行封装的UTM应该说是最佳选择了。

3. 安装

关于在MAC上安装UTM并安装虚拟操作系统的方法，参考这篇就够了：Install Ubuntu ARM64 on Apple M1。

因为这篇讲的是如何安装ARM64架构的虚拟操作系统，因此对于需要安装x86虚拟系统的用户需要自行调整：

在这里选择x86_64，而不是ARM64。其他都一致即可。最后不要忘记在虚拟机内安装：sudo apt install spice-vdagent spice-webdavd。

4. 文件共享

因为装过一次之后就没怎么使用过UTM了，而且也没打算装第二次。这里就留点之前的笔记：

关闭虚拟机
在面板里选择共享目录
重开虚拟机
curl http://127.0.0.1:9843/ 查看是否有可访问内容
sudo apt install davfs2
mkdir -p /home/jonathan/mnt
sudo mount -t davfs -o uid=jonathan -o gid=jonathan http://127.0.0.1:9843/ /home/jonathan/mnt
sudo mount -t davfs http://127.0.0.1:9843/ /home/jonathan/mnt
skip username & password, no such setting

使用umount来卸载挂载盘
sudo umount /home/jonathan/mnt
会显示 target is busy
需要安装工具来查看使用者
sudo apt install psmisc
查看使用情况
fuser -mv /home/jonathan/mnt
杀掉使用者进程
fuser -kv /home/jonathan/mnt

自启动装载：
https://github.com/utmapp/UTM/wiki/Useful-tips#permanently-via-fstab

cat << EOF | sudo tee -a /etc/fstab

# UMT webdav server
http://localhost:9843 /home/jonathan/mnt davfs _netdev,user,uid=jonathan,gid=jonathan 0 0
EOF

cat << EOF | sudo tee -a /etc/davfs2/secrets

# fake credentials for UMT webdav server
/home/jonathan/mnt hello world
EOF

sudo mount /home/jonathan/mnt

5. 端口转发

主要还是为了虚拟机和宿主机之间能像两台主机一样进行ssh连接：

网络面板有个高级设置，勾选
下面会有个新建，使用TCP，然后guest（虚拟机）设置0.0.0.0端口22，主机（宿主机）设置127.0.0.1端口52222
重新启动虚拟机，然后自宿主机上进行ssh登录
ssh jonathan@localhost -p 52222

WIN10安装WSL

Mon, 04 Oct 2021 02:02:22 GMT

1. 前言
2. 资源

1. 前言

之前在WIN10上有一些linux相关需求，因此安装过一次WSL2，这里稍微留点笔记。但因为这货实在是使用频率极低，大概率不会安装第二次，因此细节就不过多补充了，就留点link。

2. 资源

安装步骤可以参考：在Windows 10中启动WSL2 并安装Linux（ Ubuntu 为例）并运行docker
WSL也有版本，从1升级到2可以参考：win10 wsl1 转换为 wsl2 的方法及实际使用案例
WSL内核更新，下载链接，参考：WSL 2 需要更新其内核组件
网络问题：
- 很多时候我们会需要把WSL实例作为一个单独的主机来对待，那么就需要这个实例在局域网中有对应的入口，能够和WIN10相互通讯，这里有几篇可以看下：
- Windows重定向端口转发请求到WSL2
- 一口气搞定 WSL2 的网络问题 #12
- 如何在WINDOWS 10中打开防火墙端口

MAC ARM 兼容性问题

Sun, 03 Oct 2021 02:02:22 GMT

1. 前言
2. 兼容性问题
- brew
- docker
- node.js
  - nvm
  - dep

1. 前言

年头上更换的M1 MAC ARM架构，当时确实还是遇到了点兼容性问题的。当然全部都是编程方面的问题，不得不夸奖下Rosetta 2，确实强大。因为解决兼容性的时候遇到的一些问题的细节笔记已经丢失，所以这篇文章不会带太多细节，主要是一些指导性、方向性的解释。

2. 兼容性问题

brew

brew也是分arm和x86的，按我目前的经验来说只要装一份arm的就够了，不需要保持两个brew命令同时存在。arm版本的安装操作可以参考：M1芯片Mac上Homebrew安装教程。

docker

在使用docker build和docker run的时候都要记得指定--platform来确定镜像是intel还是arm：

linux/x86_64
linux/arm64

特别是run的时候，有的时候会默认去抓取intel的镜像，就导致启动的时候各种问题。

此外还有一个问题，有一些动作比较慢的厂商，比如说couchbase迄今为止都没有arm的image。这就很头痛了，不过没什么好办法，只能慢慢等。

node.js

node的兼容性分两方面，一是node自身的平台及版本管理，另一个就是项目代码里的依赖包的兼容性问题。

nvm

建议使用nvm来进行node的版本管理，官方文档里有关于MAC的相关问题指引：macOS Troubleshooting。

node在v15之前的版本是没有arm二进制包的，所以arm的环境nvm安装会从源码开始安装，并得到arm版本的node：

$ node -p process.arch
arm64

官方发布包地址：nodejs.org/dist/latest-v16.x

dep

因为node安装的时候是arm的，然后大量的dep包实际上也是没有arm的二进制包的，所以在编译的时候会遇到各式各样的问题（如果你安装的dep包的版本特别老的话，就更容易遇到，如果版本比较新的话，很多都已经制作了arm对应的binary）。

这里可以按刚才的nvm官方文档里提到的，把整个command line bash环境改成intel的，来进行安装x86的node。这样dep包在安装的时候会和node保持一致，都是x86的，就会更少遇到问题。

# Check what version you're running:
$ node --version
v14.15.4
# Check architecture of the `node` binary:
$ node -p process.arch
arm64
# This confirms that the arch is for the M1 chip, which is causing the problems.
# So we need to uninstall it.
# We can't uninstall the version we are currently using, so switch to another version:
$ nvm install v12.20.1
# Now uninstall the version we want to replace:
$ nvm uninstall v14.15.4
# Launch a new zsh process under the 64-bit X86 architecture:
$ arch -x86_64 zsh
# Install node using nvm. This should download the precompiled x64 binary:
$ nvm install v14.15.4
# Now check that the architecture is correct:
$ node -p process.arch
x64
# It is now safe to return to the arm64 zsh process:
$ exit
# We're back to a native shell:
$ arch
arm64
# And the new version is now available to use:
$ nvm use v14.15.4
Now using node v14.15.4 (npm v6.14.10)

dep包的安装问题就一个指导思想：更新dep包的版本，更新到有arm的binary的版本，就不会有问题了，切忌闷头在那边找源码编译的问题的解决办法。无他，主要是太浪费时间了。。。

没什么感觉的可以看看这些，你就知道有多痛苦了：

OSX LocateMe

Sat, 02 Oct 2021 02:02:22 GMT

1. 前言
2. 安装
3. 使用

1. 前言

locateme是一个命令行工具，能够调用osx系统自带的apple定位服务来给出经纬数据。

Github：netj/LocateMe。下载站：iHarder.net LocateMe。

2. 安装

可以从下载站下载软件包之后解压并放到bin下面，当然更推荐使用brew安装：

$ brew update --verbose && brew install locateme --verbose
$ which locateme
/usr/local/bin/locateme

这还没完，接下来要先使用一次locateme，会报错：

$ locateme

2021-08-31 10:47:01.299 locateme[32912:640457] [error code] != kCLErrorLocationUnknown: Error Domain=kCLErrorDomain Code=1 "(null)"
2021-08-31 10:47:01.299 locateme[32912:640457] Error: Error Domain=kCLErrorDomain Code=1 "(null)"

然后打开系统偏好设置 > 安全性与隐私 > 定位服务，勾选LocateMe。然后再尝试使用，应该就OK了：

$ locateme

<+XX.23453090,+XXX.48293057> +/- 65.00m (speed -1.00 mps / course -1.00) @ 2021/8/28 中国标准时间 XX:XX:XX

3. 使用

$ locateme -h
USAGE: locateme [options]
Version: 0.2.1
Outputs your current location using Apple's geolocation services.
  -h          This help message
  -g          Generate a Google Map URL
  -l          Generate long, multiline format
  -f format   Generate a custom output with the following placeholders
     {LAT}    Latitude as a floating point number
     {LON}    Longitude as a floating point number
     {ALT}    Altitude in meters as a floating point number
     {SPD}    Speed in meters per second as a floating point number
     {DIR}    Direction in degrees from true north as a floating point number
     {HAC}    Horizontal accuracy in meters as a floating point number
     {VAC}    Vertical accuracy in meters as a floating point number
     {TIME}   Timestamp (with date) of the location fix
     {HOST}   Computer hostname

Examples:

 Command: locateme -f "lat={LAT},lon={LON}"
 Output : lat=12.34567,lon=98.76543

 Command: locateme -f "<lat>{LAT}</lat><lon>{LON}</lon><alt>{ALT}</alt>"
 Output : <lat>12.34567</lat><lon>98.76543</lon><alt>123</alt>

一般这样用：

$ locateme -f "{\"lat\":\"{LAT}\",\"lon\":\"{LON}\"}"

{"lat":"XX.234463","lon":"XXX.482957"}

高德地图 API

Sat, 25 Sep 2021 03:02:22 GMT

1. 前言
2. 账号申请与准备
3. 常用API

1. 前言

地图服务主要就百度和高德两家，百度的API之前有接过，这次简单尝试下高德的API。基本上可以说大同小异，没什么本质差别。大概从一些客制化的方面会有些差别吧，主要是一些比较细节的功能方面。

API主页：高德开放平台。

2. 账号申请与准备

首先进行账号注册，然后到console创建API Key：

创建应用：左边栏应用管理 > 我的应用 => 右上部按钮创建新应用
添加Key：在创建出来的应用，右上部按钮添加
- 这里注意，有两类KEY是比较常用的：
  - Web端(JS API)：这个KEY是用在浏览器内，或内嵌Web端的，e.g 地图选点组件
  - Web服务：这个KEY是用在restful api调用的，e.g curl …
- 这两者的名字有一定的误导性，注意使用时的区分，一般可以把前者称为WebKey，后者称为ApiKey

API Key是后续调用接口的关键，所以首先需要创建这两者。

3. 常用API

全体Web API的列表可以到这里查阅文档：开发 > Web服务 API > 入门指南。

3.1 逆地理编码

实际上就是根据经纬查找地点信息：文档。

$ curl "https://restapi.amap.com/v3/geocode/regeo?output=json&location=116.310003,39.991957&key=2e06f02c891a78a0b3860e75ebc8702b&radius=100"

{
  "status": "1",
  "regeocode": {
    "addressComponent": {
      "city": [],
      "province": "北京市",
      "adcode": "110108",
      "district": "海淀区",
      "towncode": "110108015000",
      "streetNumber": {
        "number": "5号",
        "location": "116.310454,39.992734",
        "direction": "东北",
        "distance": "94.5489",
        "street": "颐和园路"
      },
      "country": "中国",
      "township": "燕园街道",
      "businessAreas": [
        []
      ],
      "building": {
        "name": "北京大学",
        "type": "科教文化服务;学校;高等院校"
      },
      "neighborhood": {
        "name": "北京大学",
        "type": "科教文化服务;学校;高等院校"
      },
      "citycode": "010"
    },
    "formatted_address": "北京市海淀区燕园街道北京大学"
  },
  "info": "OK",
  "infocode": "10000"
}

这个API返回的city是空数组，不太清楚是不是因为直辖市的原因
注意这里的formatted_address，后面可以结合另一个API使用

3.2 地理编码

可以根据3.1里提到的formatted_address来查找具体的地点信息：文档。

$ curl "https://restapi.amap.com/v3/geocode/geo?key=2e06f02c891a78a0b3860e75ebc8702b&address=北京市海淀区燕园街道北京大学"

{
  "status": "1",
  "info": "OK",
  "infocode": "10000",
  "count": "1",
  "geocodes": [
    {
      "formatted_address": "北京市海淀区北京大学",
      "country": "中国",
      "province": "北京市",
      "citycode": "010",
      "city": "北京市",
      "district": "海淀区",
      "township": [],
      "neighborhood": {
        "name": [],
        "type": []
      },
      "building": {
        "name": [],
        "type": []
      },
      "adcode": "110108",
      "street": [],
      "number": [],
      "location": "116.305469,39.989481",
      "level": "兴趣点"
    }
  ]
}

3.3 选址组件

开发 > 地图组件 > 开发指南 > 选址组件：文档。

需要注意，这个组件和刚才的2个API不同，刚才的2个API使用的是Web服务API Key，而这个组件则需要使用Web端(JS API)API Key。千万不要搞错了。

内嵌一个iframe到web页面上之后，就可以通过文档中的代码进行初始化。当用户点击下面的地址列表中的某一个地址时，就会触发事件，返回给开发者以下信息：

{
  "address": "颐和园路5号",
  "location": "116.310003,39.991957",
  "name": "北京大学"
}

3.4 套路

一般来说可以这样做：

在app或web中嵌入3.3 选址组件，然后获得用户所选地点的经纬度
然后将经纬度传入3.1 逆地理编码获得到formatted_address
最后通过3.2 地理编码来获得地点的省市等信息

根据3.1和3.2两者的返回，可以拼装出完整的地点信息。

Weather API

Sat, 25 Sep 2021 02:02:22 GMT

1. 前言
2. OpenWeather
3. Nowapi

1. 前言

平时做一些和生活、日常应用相关的功能时，偶尔会有些需要获取天气信息的功能。所以简单了解了点天气相关的API。之前在知乎上搜了下，找到一个topic：网上的天气 API 哪一个更加可靠？。

不过总感觉国内的API一般都不咋的，所以兴趣不大，也没怎么尝试。下面简单介绍下尝试过的两个。

2. OpenWeather

国外推荐使用这个：OpenWeather。注册之后就会获得token / API Key，基本上调用API也只需要这个token。

价格：Pricing。免费版的账号限制：

60 calls/minute
1,000,000 calls/month

而且免费版的账号有一些API是无法调用的，比如说查询历史天气信息。

可供使用的API清单：Weather API。基本上和天气相关你想得到的，都能得到满足。下面会举几个常用的API例子，注意所有的API返回的温度都是开氏温度，需要提供如下参数才可以转为摄氏温度：

name	mandatory	description
units	optional	Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default.

Current Weather Data

$ curl "https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}"

$ curl "https://api.openweathermap.org/data/2.5/weather?q={city name},{state code}&appid={API key}"

$ curl "https://api.openweathermap.org/data/2.5/weather?q={city name},{state code},{country code}&appid={API key}"

{
  "coord": {
    "lon": -122.08,
    "lat": 37.39
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 282.55,
    "feels_like": 281.86,
    "temp_min": 280.37,
    "temp_max": 284.26,
    "pressure": 1023,
    "humidity": 100
  },
  "visibility": 16093,
  "wind": {
    "speed": 1.5,
    "deg": 350
  },
  "clouds": {
    "all": 1
  },
  "dt": 1560350645,
  "sys": {
    "type": 1,
    "id": 5122,
    "message": 0.0139,
    "country": "US",
    "sunrise": 1560343627,
    "sunset": 1560396563
  },
  "timezone": -25200,
  "id": 420006353,
  "name": "Mountain View",
  "cod": 200
}

Historical weather API

$ curl "https://history.openweathermap.org/data/2.5/history/city?q={city ID},{country code}&type=hour&start={start}&end={end}&appid={API key}"

$ curl "https://history.openweathermap.org/data/2.5/history/city?q={city ID},{country code}&type=hour&start={start}&cnt={cnt}&appid={API key}"

{
  "message": "",
  "cod": "200",
  "city_id": 2885679,
  "calctime": 0.0823,
  "cnt": 3,
  "list": [
    {
      "main": {
        "temp": 266.052,
        "temp_min": 266.052,
        "temp_max": 266.052,
        "pressure": 957.86,
        "sea_level": 1039.34,
        "grnd_level": 957.86,
        "humidity": 90
      },
      "wind": {
        "speed": 1.16,
        "deg": 139.502
      },
      "clouds": {
        "all": 0
      },
      "weather": [
        {
          "id": 800,
          "main": "Clear",
          "description": "Sky is Clear",
          "icon": "01n"
        }
      ],
      "dt": 1485722804
    },
    {
      "main": {
        "temp": 263.847,
        "temp_min": 263.847,
        "temp_max": 263.847,
        "pressure": 955.78,
        "sea_level": 1037.43,
        "grnd_level": 955.78,
        "humidity": 91
      },
      "wind": {
        "speed": 1.49,
        "deg": 159
      },
      "clouds": {
        "all": 0
      },
      "weather": [
        {
          "id": 800,
          "main": "Clear",
          "description": "Sky is Clear",
          "icon": "01n"
        }
      ],
      "dt": 1485749608
    },
    {
      "main": {
        "temp": 274.9,
        "pressure": 1019,
        "temp_min": 274.15,
        "temp_max": 275.15,
        "humidity": 88
      },
      "wind": {
        "speed": 1,
        "deg": 0
      },
      "clouds": {
        "all": 76
      },
      "weather": [
        {
          "id": 500,
          "main": "Rain",
          "description": "light rain",
          "icon": "10d"
        }
      ],
      "dt": 1485773778
    }
  ]
}

3. Nowapi

偶然搜到的这个API，国内公司。准确度暂时没有认真校对过，这个存疑，有需要用的需要认真看下。

这家公司做的API还相当多，全部列表在这里：Nowapi。

天气API主要有下面这几个接口：

天气预报(整合版)
天气预报(5-7天)
实时天气
实时天气(批量)
历史天气
PM2.5
AQI生活指数(5-7天)
城市列表天气类型

注册账号之后在后台就可以看到自己的AppKey和Sign，这两个是用来调API的。

付费方面主要有两种形式：

按API调用频次分价格段的包月
按API实际使用次数购买次数

价格可以说相当亲民，轻度使用￥10买个15000次可以用很久了。

包月

买次数

选两个API看下：

实时天气

$ curl https://sapi.k780.com/?app=weather.today&weaId=1&appkey=10003&sign=b59bc3ef6191eb9f747dd4e83c99f2a4&format=json (示例中sign会不定期调整)

{
  "success": "1",
  "result": {
    "weaid": "1",
    "days": "2014-07-30",
    "week": "星期三",
    "cityno": "beijing",
    "citynm": "北京",
    "cityid": "101010100",
    "temperature": "31℃/24℃",
    /*当日温度区间 (注: 夜间只有一个温度如24℃/24℃)*/
    "temperature_curr": "21℃",
    /*当前温度*/
    "humidity": "50%",
    /*湿度*/
    "aqi": "100",
    /*pm2.5 说明详见weather.pm25*/
    "weather": "多云转晴",
    /*天气*/
    "weather_icon": "http://api.k780.com/upload/weather/d/1.gif",
    /*气象图标 全部气象图标下载*/
    "weather_icon1": "",
    /*无意义不必理会*/
    "wind": "微风",
    /*风向*/
    "winp": "小于3级",
    /*风力*/
    "temp_high": "31",
    /*最高温度*/
    "temp_low": "24",
    /*最低温度*/
    "humi_high": "87.8",
    /*最大湿度 [历史遗留栏位不再更新]*/
    "humi_low": "75.2",
    /*最小湿度 [历史遗留栏位不再更新]*/
    "weatid": "2",
    /*天气ID，可对照weather.wtype接口中weaid*/
    "weatid1": "",
    /*无意义不必理会*/
    "windid": "1",
    /*风向ID(暂无对照表)*/
    "winpid": "2"
    /*风力ID(暂无对照表)*/
    "weather_iconid": "1"
    /*气象图标编号,对应weather_icon 1.gif*/
  }
}

历史天气

$ curl https://sapi.k780.com/?app=weather.history&weaId=1&date=2015-07-20&appkey=10003&sign=b59bc3ef6191eb9f747dd4e83c99f2a4&format=json

{
  "success": "1",
  "result": [
    {
      "weaid": "1",
      "week": "星期一",
      "cityno": "beijing",
      "citynm": "北京",
      "cityid": "101010100",
      /*气象编号*/
      "uptime": "2015-07-20 00:50:00",
      /*更新时间*/
      "temperature": "22℃",
      /*该时段温度*/
      "humidity": "97%",
      /*该时段湿度*/
      "aqi": "101",
      /*PM2.5 AQI*/
      "weather": "晴",
      /*该时段天气*/
      "weather_icon": "http://api.k780.com/upload/weather/d/0.gif",
      /*时段气象图标 全部气象图标下载*/
      "wind": "东北风",
      /*该时段风向*/
      "winp": "1级",
      /*该时段风力*/
      "temp": "22",
      /*温度*/
      "weatid": "1",
      /*天气编号*/
      "windid": "13",
      /*风向编号*/
      "winpid": "201"
      /*风力编号*/
      "weather_iconid": "1"
      /*气象图标编号,对应weather_icon 0.gif*/
    },
    {
      "weaid": "1",
      "week": "星期一",
      "cityno": "beijing",
      "citynm": "北京",
      "cityid": "101010100",
      "uptime": "2015-07-20 01:50:00",
      "temperature": "22℃",
      "humidity": "99%",
      "aqi": "101",
      "weather": "晴",
      "weather_icon": "http://api.k780.com/upload/weather/d/0.gif",
      "wind": "东北风",
      "winp": "1级",
      "temp": "22",
      "weatid": "1",
      "windid": "13",
      "winpid": "201"
    }
  ]
}

Vegeta Notes

Sat, 11 Sep 2021 03:02:22 GMT

1. 工具选择
2. 后端示例
3. vegeta command
4. vegeta attack
- 4.1 vegeta attack: target from stdin
- 4.2 vegeta attack: target from file
5. vegeta plot
6. vegeta report
7. vegeta encode
8. Others

1. 工具选择

压力测试也是后端工作中比较多见的需求。一般来说，针对简单的HTTP请求，用得比较多的是：ab - Apache HTTP server benchmarking tool & wg/wrk。这两款都是使用C语言进行编写的工具，性能有十分保障。

但日常工作中，我们的压测还有一些灵活的需求：

压测的目标不一定是单个的API
压测的时长和速率需要能调节
压测的结果要能快速展示，包括文字和graph两种形式
压测的结果要能进行存储，以使用其他软件进行拓展研究
压测要能以client端分布式的方式进行，以保证在制造巨量的请求时，可以使用多台client进行联合测试，且测试结果可以融合归一进行分析

以上的几点需求，在ab和wrk中都不能完全满足，特别是分布式测试这点，基本上没见过市面上有哪个软件能够很好做到。

这里就要介绍下今天的主角了：tsenart/vegeta。这款工具是使用golang编写的压测工具，由于golang非常优秀的goroutine，这款工具的表现几乎不逊色于c语言编写的几位前辈。

安装：

$ brew update && brew install vegeta

2. 后端示例

本文会进行一些范例演示，所有的vegeta命令所针对的后端服务器都使用如下代码：

import * as express from 'express';

const app = express();
const port = 5000;

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get('/get', async function (req, res) {
  const data = {
    method: 'GET',
    path: '/get',
    query: req.query,
    headers: req.headers
  };
  console.log(JSON.stringify(data));
  res.json(data);
});

app.post('/post', async function (req, res) {
  const data = {
    method: 'POST',
    path: '/post',
    data: req.body,
    headers: req.headers
  };
  console.log(JSON.stringify(data));
  res.json(data);
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
});

该服务器仅只有两个API：

http://localhost:5000/get
http://localhost:5000/post

这两个API会在收到请求后，在console中打印出该请求的所有信息。

3. vegeta command

vegeta命令包含多个功能，在运行的时候，需要额外提供一个子命令，来明确目前运行的时候具体要做什么：

attack：压测命令
encode：转码命令，将压测输出的结果集从默认格式转成其他的格式（json等）
plot：graph命令，将压测输出的结果生成graph html，以供查看
report：报告命令，将压测输出的结果生成文字形式的report

vegeta使用*nix pipeline非常重，很多参数的输入和结果的输出都默认使用stdin和stdout，所以非常适合多个命令进行前后管道顺序执行。

另外需要提一点，vegeta命令中提供的所有文件的路径，都必须以当前的工作路径（cwd）为基准。

e.g

$ echo 'GET ...' | vegeta attack ... | vegeta report

4. vegeta attack

该命令用以发起压测，官方文档：link。有几个option需要简单说明下：

-targets：该option指定attack的目标是什么，默认读取stdin的输入，也可以提供一个文件路径，让vegeta读取其文本内容来获取目标
-format：该option一般使用http，表示target给的内容必须按RFC 2616的格式提供：'GET http://localhost:5000/...'
-header：该option可以提供多个，每个option表示额外提供一个header
-body：该option用来指定post body的数据文件，注意，如果在targets里也提供了@/body/file/path则以target里的为准，当前option提供的body会被忽略
-timeout：该option表示每个http请求的超时时长，默认为0表示无超时
-workers：该option用来指定vegeta刚启动时需要启动的workers数量，后续实际workers数值会根据需求自行上升以满足rate的要求
-max-workers：该option用来限制attack时的最高并发数量
-duration：该option用来控制测试时长，使用字符串形式来提供数值：5s
-rate：该option用来控制请求并发速率
- 5/s表示每秒vegeta会一共发出5个请求（vegeta会启动补充worker，如果速度设置很高的话）
- 设置为0表示无限制，vegeta会尽可能快地发出请求
- 设置为0的时候需要和max-workers配合使用，来行成一个固定的并发速率，否则可能会快速耗尽系统资源

4.1 vegeta attack: target from stdin

如下命令启动5秒的测试，并每秒发送5个请求，最后以文字形式输出报告。

vegeta attack从自己的stdin读取echo的字符串作为target进行压测
vegeta report从自己的stdin读取上一个命令vegeta attack的stdout，来获取数据进行处理

$ echo 'GET http://localhost:5000/get?get_key=get_val' | \
    vegeta attack \
        -duration=5s \
        -rate=5/s \
        -format=http \
        -header 'Cache-Control: no-cache' | \
            vegeta report -type=text

服务端输出：

Server listening at http://localhost:5000
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"0","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"1","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"2","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"3","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"4","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"5","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"6","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"7","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"8","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"9","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"10","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"11","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"12","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"13","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"14","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"15","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"16","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"17","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"18","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"19","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"20","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"21","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"22","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"23","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-vegeta-seq":"24","accept-encoding":"gzip"}}

report：

Requests      [total, rate, throughput]         25, 5.21, 5.21
Duration      [total, attack, wait]             4.799s, 4.798s, 1.073ms
Latencies     [min, mean, 50, 90, 95, 99, max]  1.023ms, 1.57ms, 1.386ms, 1.97ms, 2.819ms, 4.442ms, 4.442ms
Bytes In      [total, mean]                     6762, 270.48
Bytes Out     [total, mean]                     736, 29.44
Success       [ratio]                           100.00%
Status Codes  [code:count]                      200:25  
Error Set:

4.2 vegeta attack: target from file

如下命令会启动持续5秒的测试，并每秒发送5个请求，请求内容来自targets.txt文件的内容，最后以文字形式输出报：

vegeta attack \
    -targets=./vegeta/targets.txt \
    -duration=5s \
    -rate=5/s \
    -format=http \
    -header 'Cache-Control: no-cache' | \
        vegeta report -type=text

targets.txt

GET http://localhost:5000/get?get_key=get_val
X-Add-Get-ID1: 78
X-Add-Get-ID2: 88

POST http://localhost:5000/post?post_key1=post_val
X-Add-Post-ID: 199
Content-Type: application/json
@./vegeta/postdata.json

POST http://localhost:5000/post?post_key2=post_val
X-Add-Post-ID: 299
Content-Type: application/json
@./vegeta/postdata.json

postdata.json

{
  "postdata": {
    "a": 1,
    "b": 2
  }
}

vegeta发送的请求会以targets.txt内列的target一个个请求发送下去
每个target下面可以附带额外的header，不限数量，每行一个header
POST的target可以在下面带上一行@/body/file/path格式的文本，表示读取该位置的文件，作为post的body使用

服务端输出：

Server listening at http://localhost:5000
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"0","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"1","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"2","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"3","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"4","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"5","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"6","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"7","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"8","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"9","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"10","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"11","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"12","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"13","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"14","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"15","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"16","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"17","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"18","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"19","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"20","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"21","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"199","x-vegeta-seq":"22","accept-encoding":"gzip"}}
{"method":"POST","path":"/post","data":{"postdata":{"a":1,"b":2}},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","content-length":"46","cache-control":"no-cache","content-type":"application/json","x-add-post-id":"299","x-vegeta-seq":"23","accept-encoding":"gzip"}}
{"method":"GET","path":"/get","query":{"get_key":"get_val"},"headers":{"host":"localhost:5000","user-agent":"Go-http-client/1.1","cache-control":"no-cache","x-add-get-id1":"78","x-add-get-id2":"88","x-vegeta-seq":"24","accept-encoding":"gzip"}}

可以看到，根据我们的option设置，一共是25个请求5s * 5/s。然后请求和targets.txt里指定的一样，每次都是按1个GET2个POST这样的顺序发送。3*8=24之后，正好还有一个待发的，因此最后就是一个GET。

report：

Requests      [total, rate, throughput]         25, 5.21, 5.21
Duration      [total, attack, wait]             4.802s, 4.801s, 1.344ms
Latencies     [min, mean, 50, 90, 95, 99, max]  1.093ms, 1.687ms, 1.379ms, 1.769ms, 3.979ms, 5.077ms, 5.077ms
Bytes In      [total, mean]                     6762, 270.48
Bytes Out     [total, mean]                     736, 29.44
Success       [ratio]                           100.00%
Status Codes  [code:count]                      200:25  
Error Set:

5. vegeta plot

该命令用来将测试结果输出成graph的html，官方文档：link。option基本不需要调整。这里需要注意，输出的graph只含latency，不含其它信息。

e.g

$ echo "GET http://:80" | vegeta attack -name=50qps -rate=50 -duration=5s > results.50qps.bin
$ cat results.50qps.bin | vegeta plot > plot.50qps.html
$ echo "GET http://:80" | vegeta attack -name=100qps -rate=100 -duration=5s > results.100qps.bin
$ vegeta plot results.50qps.bin results.100qps.bin > plot.html

6. vegeta report

该明星用来将测试结果转换为报告，官方文档：link。

options：

--type：报告类型：text | json | hist[buckets] | hdrplot
--every：报告间隔，设置该值会在测试中也渐次输出report，e.g --every=1s

e.g

$ echo "GET http://:80" | vegeta attack -rate=10/s > results.gob
$ echo "GET http://:80" | vegeta attack -rate=100/s | vegeta encode > results.json
$ vegeta report results.*

7. vegeta encode

该命令用来将测试结果转换成其他格式，默认输出自vegeta attack的格式是gob，官方文档：link。

可以转换为：

gob
json
csv

使用option--to来进行指定。

e.g

$ echo "GET http://:80" | vegeta attack -rate=1/s > results.gob
$ cat results.gob | vegeta encode | jq -c 'del(.body)' | vegeta encode -to gob

8. Others

8.1 动态targets

根据官方instruction Usage: Generated targets，可以动态生成压测的target。另外也可以通过vegeta attack -targets=...的方式提供测试目标文件，然后在该文件中列出期望的用户行为来进行拟真测试。

8.2 分布式压测

这也是在开篇的时候提到的比较重要的一点需求：Usage: Distributed attacks。可以按该官方指引在多台client上进行分布式压测，vegeta有一点很好的是可以组合各个client生成出来的gob文件，来生成一份最终的结果report。

8.3 压测实时分析

Usage: Real-time Analysis，可以查看压测实时的运行状态。

Gatsby Notes

Sun, 05 Sep 2021 03:02:22 GMT

1. Wordpress -> Jekyll -> Gatsby
2. 选择Starter
3. 如何管理你的repo
4. Gatsby技术开发

1. Wordpress -> Jekyll -> Gatsby

开博也不算特别早，11年开始的，正好10年，当时基本上没什么选择：Godaddy + VPS + Wordpress。后来github搞出了免费的page，加上jekyll提供了不错的静态化工具，也就顺理成章换成了Jekyll + Github Page。第一次更换还算比较简单，Wordpress的旧post全部转换成静态html，所有资源都是内嵌的，然后放到jekyll的一个文件夹里就完事了，然后后续使用jekyll来编译md文件成静态html，后续的post也能便捷接续上。

断断续续也写了点关于jekyll blog的维护文章：Jekyll的安装。

不过后续使用jekyll也遇到了一些问题：

ruby技术栈，不熟悉，导致要做一些customization很不方便
gem有的时候总是会遇到安装问题
jekyll的theme定了一个之后基本上就没办法换成其他的了（这个问题在gatsby上也有，后面会提供解决方法），然后我之前选的一款theme比较老，就导致了很多问题，比如说手机浏览不友好等
一些比较现代化的website应该有的功能都没有，比如说浏览器兼容性等，其实主要还是因为上一条
功能相对来说比较简单，毕竟jekyll真的是一款很纯粹的静态化站点工具

说到底，关键的问题还是技术栈，如果是基于node的话，很多问题其实我都可以自己解决。于是今年就想换到node技术栈，看了下，其实也就gatsby比较强大点。

这里需要澄清一点：Gatsby是一个建站工具集，而不是Jekyll这样的静态站点工具。这两者是有本质区别的：

Jekyll只能用来做静态网站，也就是说将md内容构建成一系列的静态html内容，放到host上
Gatsby主要是用来做网站建设的，你需要什么类型的网站，静态的还是带后台数据库的，gatsby都可以帮你搞定，而不仅仅只是静态的CMS型的网站

可以看下WHY GATSBY了解下：

Gatsby功能非常强大，对我来说有利有弊：

pros：

gatsby工具集、插件系统非常强大，各种客制化需求都可以自行满足
gatsby基于reactjs，要制作一些自己的组件非常容易上手
gatsby有大量现成的starter或theme等，几乎任何简单的需求都可以直接使用，不需要额外的开发
gatsby的工具集提供的功能都非常现代化，响应式页面、浏览器兼容性等都不在话下，建出来的站点功能完备

cons：

gatsby过于强大，很多东西存在但对我来说无用，反而可能会有维护负担（漏洞、版本升级等）
gatsby的graphql系统对我来说太复杂了，我只是要一个静态站点而已
gatsby需要上手时间来学习和了解里面的细节，它有自己的系统和API等，都是需要时间熟悉的，而不是像jekyll那样几个CLI命令就搞定一切了

Anyway，最后反正还是切到了Gatsby。不过因为wordpress之前转到jekyll的时候是通过生成一部分静态html直接存放在jekyll的repo里的方式进行的。到了gatsby这步就行不通了，gatsby是整站完全由CLI生成的，我简单研究了下，没找到像jekyll那时候的那种能兼容两种行为的模式。最后只能忍痛抛弃掉了转到jekyll之前的那部分博客内容，还好量不算特别大。

2. 选择Starter

要使用Gatsby开始建站，必然首先会需要选择一款Starter，在其基础上进行二次制作/设置/内容输出（什么？你说你想直接用gatsby基础库裸做一个站点？那你为什么不直接用react得了，gatsby一堆API那么复杂，何必呢）。选择Starter可以去Gatsby的官方站点：Gatsby Starter Library，然后用命令行工具来进行操作：

$ gatsby new {your-project-name} {link-to-starter}

不过实际上这个命令也就是帮你clone了一个repo出来而已，没啥意义，建议看我后面的第三点来进行初始化和repo管理。

我个人选的是：gatsby-starter-lumen。虽然没什么出彩的地方，但至少功能比较齐全，而且我看了看还有稳定的维护记录，不过应该也不能算是active了，到现在（20210905）仍旧用的是Gatsby的2.X的版本，Gatsby官方Release都已经是3.14.X了。如果现在还有人入坑的话，那建议还是要选一款支持v3以后Gatsby版本的Starter。

3. 如何管理你的repo

静态站点的repo管理建议如下：

制作一个repo专门放gatsby相关内容，建议使用bitbucket制作一个单人用的private repo：Bitbucket
制作一个单独的github page repo，来收取gatsby build出来的静态内容，作为静态站点的host：Github Pages

至于为什么要这么做：

鸡蛋不同篮，保证安全，原始数据和静态站点尽量分开
如果你的站点里有任何会导致版权争议之类的内容，也只会有github page repo被take down，而不会影响到你的原始数据
务必保证你的原始数据一定要保存在一个private repo里，否则极容易被和page repo一起take down

因为我的原始数据repo是放在bitbucket的，就不能直接使用github的fork了。这里可以打开Bitbucket的import页面，使用import的方式，把你选择的Starter的github链接贴进去，这样就会在bitbucket里创建一个private repo，里面的内容是完全clone自github的。

为了后续接收原始starter repo里的改动（新功能及版本升级之类的维护等），建议不要直接在这个repo里的master分支进行任何改动，该repo的master分支上的所有内容必须保证无变动。后续所有starter的master发生的改动就可以直接pull过来。

在本地磁盘上clone刚才创建出来的bitbucket repo后，进入这个repo

创建一个以你的站点命名的branch：xenojoshua.com
在repo根目录创建同名文件夹：xenojoshua.com
然后在里面创建一个Makefile来维护一些日常使用的命令
此外，创建一个root文件夹，把所有你的客制化内容都放在这个文件夹内，文件夹的结构和外部starter的root文件保持一致，后续就可以使用脚本将这个文件夹下的内容全部复制到根目录，这样就能在保证starter不变的情况下，添加客制化的东西
为了同步starter github原repo的内容，还需要添加一个remote，名字就叫sync，地址就是starter的github repo地址

原始数据repo和github page repo位置：

some_dir_on_disk /
                 | agreatfool.github.io / ...
                 | gatsby-starter-lumen / ...

原始数据repo文件结构：

gatsby-starter-lumen /
                     | content /
                               | pages    # starter自带的页面
                               | posts    # starter自带的范例posts
                     | src                # starter自带的组件等实现代码
                     | static /
                              | media     # starter自带的范例posts里用到的图片
                     | xenojoshua.com /
                                      | root /   # 所有内容都会在develop和build的时候覆盖到lumen根目录
                                             | content /
                                                       | pages
                                                       | posts /
                                                               | 2016 / ...
                                                               | 2017 / ...
                                                               | ...
                                                               | 2021 /
                                                                      | ...
                                                                      | 09 /
                                                                           | ...
                                                                           | gatsby-notes.md
                                             | src       # 客制化的组件代码，包括修改starter自带组件的一些行为
                                             | static /
                                                      | media /
                                                      | posts /
                                                              | 2016 / ...
                                                              | 2017 / ...
                                                              | ...
                                                              | 2021 /
                                                                     | ...
                                                                     | 09 /
                                                                          | ...
                                                                          | gatsby-notes / ... / *.jpeg
                                      | Makefile

Makefile：

sync将starter原repo里的改动同步过来：

sync:
	( \
		cd ..; \
		git checkout master -f; \
		git pull sync master --verbose; \
		git push origin master -f --verbose; \
		git checkout xenojoshua.com -f; \
		git rebase master; \
		git push origin xenojoshua.com -f; \
		cd xenojoshua.com; \
	)

develop在本地应用所有的变化，查看在xenojoshua.com文件夹下做的改动的效果：

develop:
	( \
		cd ..; \
		pwd; \
		rm -rf ./content/posts/*; \
		rm -rf ./static/media/*; \
		cp -Rf ./xenojoshua.com/root/* ./; \
		yarn add gatsby-remark-table-of-contents gatsby-plugin-image; \
		yarn develop; \
	)

build制作发布用的静态站点：

build:
	( \
		cd ..; \
		pwd; \
		rm -rf ./public; \
		rm -rf ./content/posts/*; \
		rm -rf ./static/media/*; \
		cp -Rf ./xenojoshua.com/root/* ./; \
		yarn add gatsby-remark-table-of-contents gatsby-plugin-image; \
		yarn build; \
		git checkout .; \
		git clean -fd; \
	)

deploy将最新的发布内容提交到github page repo，发布上线：

deploy:
	( \
		cd ../../agreatfool.github.io; \
		pwd; \
		git fetch; \
		git checkout -f gatsby; \
		git pull origin gatsby; \
		cd ../gatsby-starter-lumen; \
		pwd; \
		cp -Rf ./public/* ../agreatfool.github.io/; \
		cd ../agreatfool.github.io/; \
		pwd; \
		git add .; \
		git commit -m "Save."; \
		git push origin gatsby; \
	)

4. Gatsby技术开发

刚才也说到了用gatsby的最主要的原因就是能开箱即用，基本上不需要做什么改动就可以建站，但实际上多多少少还是要做点调整的。我对lumen做的改动：

blockquote太丑了，改了下样式
Feed组件改了下时间的format，改为中国人的习惯格式
Author组件改为github链接
Meta组件改了下时间的format
自制了Gallery组件：
- Gatsby Gallery组件
- 用到了额外的插件：gatsby-plugin-image

下面就简单说下gatsby里的一些技术点，因为每个starter都会对基本的gatsby进行客制化，所以我说的不一定你用得上，但大致上的概念是不会变的。另，建议先通读下Official Tutorial。

4.1 Config

root/config.js：站点的一些基本属性，url是什么，作者信息等，会被下面的gatsby配置文件加载，实际上就是gatsby-config.js的一部分
root/gatsby-config.js：其他基本可以忽略，主要是插件的配置

这里提一句如果要让_不再被转为斜体，需要修改gatsby-transformer-remark插件的配置，在options里添加：pedantic: false。

4.2 Structure

准备知识：

lumen的代码文件：

root /
     | gatsby /
              | create-pages.js    # 实现 createPages API，创建tags、categories、分页posts等页面
              | on-create-node.js  # 实现 onCreateNode API
              | on-render-body.js  # 实现 onRenderBody API
     | src /
           | assets / scss / ...   # 样式代码文件
           | components / ...      # 所有页面组件代码文件
           | templates / ...       # 所有页面的模板代码文件
     | gatsby-browser.js           # gatsby web的入口，css等就在这里加载
     | gatsby-config.js            # gatsby 的配置
     | gatsby-node.js              # gatsby node的入口，后端进程入口
     | gatsby-ssr.js               # gatsby ssr的入口，离线渲染

4.3 Graphql

Gatsby用Graphql用得很重，所有的页面上的数据都是来自graphql的查询，即便是你写的md文件post内容，也是通过graphql查询获得的。

准备知识：Part 4: Query for Data with GraphQL。

这里不准备讲太展开，这个话题有点大了，基本上读完tutorial的内容也就差不多了，更深入的就先不谈了。

建议先用develop命令把后端启起来，然后按Use GraphiQL to explore the data layer and write GraphQL queries里提到的，打开GraphiQL界面进行摸索，稍微看下就会了。

图上左边会列出所有gatsby可用的查询内容，紫色的表示是查询条件，蓝色的表示是可以得到的返回数据，点击你需要的内容，UI会自动将点中的内容填充到中间的那段查询语句里，非常便捷。查询结果也可以直接在UI上看到，基本上免去了后面到代码里调试的麻烦，只要UI上你的语句是对的，结果是你想要的，照样贴到代码里就不会错了。

4.3.1 Page query

Graphql最主要有两种使用方法，一种叫page query：

主要应用在页面初始化的时候的查询，比如说你的blog，点击某一篇post的链接，打开的时候就会去查询对应的post数据
这个查询是可以带参数的，这很重要

整个查询路径如下：

root/gatsby-node.js：启动服务器，会加载 gatsby/create-page.js
root/gatsby/create-page.js：会决定某个page的template，以及对应的page query的context：e.g source
root/src/templates/post-template.js：在对应的template文件中，在graphql查询中使用context带过来的参数，并在page组件中使用查询得到的结果：e.g source1 source2

4.3.2 Static query

Graphql另一种使用方法是static query：

可以在任何你想要进行查询的地方进行查询，不一定要像page query那样必须写在固定的地方遵照规定的流程
但这类查询必须是完全静态的，意味着你不能在query中添加任何变量
虽然写法比较自由，但实际应用范围反而很小

Gatsby Gallery组件

Sun, 05 Sep 2021 02:02:22 GMT

1. 需求
2. 文件结构
3. 代码改动

1. 需求

Gallery算是一个blog中非常基础的需求，看了下gatsby的插件库，貌似是有一个gatsby-theme-gallery。但是这个插件引入了theme概念，对我来说无用，而且我需求的并不是要一个site级别的gallery，而是一个post级别的gallery，所以不合用。还是自己做一个得了。

主要参考了：Creating a Custom Photo Gallery using Gatsby.js and CSS Grid。此外，我的gatsby使用的是alxshelepenok/gatsby-starter-lumen这个starter，技术上倒是无所谓用的是哪个starter，但文件夹结构是因应着这个starter的结构，所以姑且这里提下。

另外还有一个插件：browniebroke/gatsby-image-gallery，不过看了下用起来也蛮麻烦的，再说了。

关于gatsby的一些技术点，及如何制作自制插件之类的，会在另一篇博文里展开，这里就不提了。

2. 文件结构

这里按当前这篇post进行举例，来说明下大致上的post相关文件及gallery相关图片文件的存放位置。

root /
     | content /
               | posts /
                       | 2021 /
                              | 09 /
                                   | gallery-example.md  # 这是博文本身
     | static /
              | media /
                      | posts /
                              | 2021 /
                                     | 09 /
                                          | gallery-example /
                                                            | gallery / *.jpeg  # 将会展示在gallery内的图片
                                                            | *.jpeg            # 其他会在post内使用的图片

这篇blog的slug：gallery-example
post本身的md文件还是按slug存放在：/content/posts/YYYY/MM/${slug}.md
post对应的图片是按slug存放在：/static/media/posts/YYYY/MM/${slug}/*.jpeg
这里新添加一层gallery文件夹，里面的图片会被gallery插件使用，展示在post的EOF之后：/static/media/posts/YYYY/MM/${slug}/gallery/*.jpeg

大致上就这样，主要就是在media的post专属文件夹里新添加了一个gallery文件夹，里面的图片都会作为post的专属gallery展示在EOF之后。

这里展示一张不会在gallery里展出的图片，因为它是存放在post的media文件夹内，但在gallery文件夹之外的图片：/static/media/posts/2021/09/gallery-example/non-gallery.jpeg。

3. 代码改动

代码改动主要是下面几个：

gatsby-config.js                                 # 添加gatsby-plugin-image插件，该图片展示插件在lumen这个starter中不存在
gatsby/create-page.js                            # 在post-template.js使用的context中添加gallery参数，该值为static的media文件夹下post对应的gallery文件夹
src/types/gallery.js                             # 描述从graphql内查询出来的allFile数据结构，这会作为gallery参数传给Post
src/templates/post-template.js                   # 在该template的page query中根据create-page.js给的gallery参数，查询对应路径的图片文件信息allFile；PostTemplate的传入参数data里会有一个新的节点allFile，把它作为gallery参数传给Post
src/components/Post/Gallery/Gallery.js           # 组件实现js
src/components/Post/Gallery/Gallery.module.scss  # 组件style
src/components/Post/Gallery/index.js             # 组件index，直接引入Gallery.js
src/components/Post/Post.js                      # 判断Post新的传入参数gallery，如果里面有图片，则在Content后面追加Gallery组件

3.1 create-page.js

  createPage({
    path: edge.node.fields.slug,
    component: path.resolve('./src/templates/post-template.js'),
    context: { slug: edge.node.fields.slug, gallery: `media${edge.node.fields.slug}/gallery` }
  });

3.2 post-template.js

  query PostBySlug($slug: String!, $gallery: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      ### 
      others
      ###
    }
    allFile(filter: { relativeDirectory: { eq: $gallery } }) {
      totalCount
      nodes {
        childrenImageSharp {
          gatsbyImageData
        }
      }
    }
  }

  return (
    <Layout title={`${postTitle} - ${siteTitle}`} description={metaDescription} socialImage={socialImageUrl} >
      <Post post={data.markdownRemark} gallery={data.allFile} />
    </Layout>
  );

3.3 Gallery.js

// @flow strict
import React from 'react';
import { GatsbyImage } from 'gatsby-plugin-image';
import styles from './Gallery.module.scss';
import type { GalleryData } from '../../../types/gallery';

type Props = {
  gallery: GalleryData
};

const Gallery = ({ gallery }: Props) => {
  const images = [];
  // eslint-disable-next-line no-restricted-syntax
  for (const [index, node] of gallery.nodes.entries()) {
    const imgKey = `gallery-img-${index}`;
    const sharp = node.childrenImageSharp[0];
    if (sharp) {
      const image = sharp?.gatsbyImageData;
      if (image) {
        images.push(
          <GatsbyImage key={imgKey} alt={imgKey} image={image} />
        );
      }
    }
  }

  if (images.length > 0) {
    return (
      <div className={styles['gallery']}>
        {images}
      </div>
    );
  }
  return null;
};

export default Gallery;

3.4 Post.js

  <div className={styles['post__content']}>
    <Content body={html} title={title} />
    {galleryNode}
  </div>

如何管理个人笔记

Sat, 28 Aug 2021 02:02:22 GMT

1. 笔记分类
2. 工具选择
3. 备份和安全
4. DayOne的问题
5. 个人感悟的工具选择
6. Obsidian

1. 笔记分类

笔记管理是非常重要的，无论是小时候老生常谈的剪报修养，到读书学习时候的课堂笔记，再到后来的个人博客，无非就是将经验积累下来，转化为文字形态进行存储。无论其子概念范畴是什么，其实一律可以归类为「笔记」。

这里简单分享下个人的笔记分类，主要以可见度为第一维度分类，以内容和类型为第二维度分类（不存在微博、twitter之类的短文字内容，这类内容不足以被称为笔记）：

公众可见：
- 个人博客：进行一些经验分享和探讨（comment形式），以技术内容为主，辅以少量政经评论
个人私密：
- 剪藏笔记：主要是通过剪藏的方式进行存储的一些资料，包括技术内容的以及政经内容的各种方向资料
- 日记
- 个人感悟：日常的一些体悟和思想积累，也包括游记等娱乐内容

其负责的领域各不相同：

个人博客主要进行技术分享，其实本来也有政经探讨的意向，但因为国情问题，还是不方便在公众场合进行这类分享
剪藏笔记属于非常重要的一块，不过这块基本上都不是原创内容，是从网络各个频道上剪藏过来的内容，和老旧概念剪报属于一个意思。这部分内容最主要是构建个人知识数据库，需要高效的工具进行管理，方便后续的搜索和查询
个人感悟这块纯原创，主要把人生中的各种想法和经历记录下来，以免一辈子白活

2. 工具选择

根据上面的分类，工具主要分3部分：

个人博客：
- 静态博客系统，使用github来进行host
- 至于静态博客系统选哪家，那实在可选的工具太多了，大家根据自己的技术栈来进行选择即可
- 目前我个人刚从jekyll转到gatsby，后面应该也会撰文记录细节
剪藏笔记：
- 目前市面上的选择应该也比较多了，这块推荐印象笔记以及剪藏插件，再加上印象笔记官方微信公众号的剪藏功能，可以保证全平台覆盖
- 印象笔记的tagging和搜索功能都做的很强大，非常好用
个人感悟：
- 之前使用的是dayone，目前转到了obsidian使用静态文件系统进行管理
- 这块属于本文的重点内容后面细说

阮一峰的博文「最适合程序员的笔记软件」，可以仔细阅读下。

3. 备份和安全

无论上述的任何一个分类，数据安全都是非常重要的，当然需要有针对性的对策：

个人博客：之前也提到了使用静态博客系统，既然如此这块自然会使用git进行代码/内容管理，git本身就是分布式的，remote一份，本地磁盘一份，OSX的TimeMachine一份
剪藏笔记：这块主要靠印象笔记的云服务，云端一份，本地磁盘一份，OSX的TimeMachine一份
个人感悟：目前使用obsidian，iCloud一份，本地磁盘一份，OSX的TimeMachine一份

4. DayOne的问题

使用DayOne的时间也很久了，这款软件的版本演进引入了相当激进的行为变化，导致了一系列的问题。

早期程序行为：

markdown优先，编辑操作非常轻松愉快
数据存储完全依赖文件系统，每个post一个单独的文件，附件则全部存储到一个统一的文件夹内

这就保证了：

程序员型的编辑者创造内容有非常愉悦的编写体验
内容所见即所得，不需要手动操作菜单界面
备份非常简单便捷，直接存放到备份文件系统即可
后续切换到其他的编辑软件非常方便，只要是支持markdown语法的编辑软件都可以直接使用，如果不考虑过于复杂的内容维护和搜索等
数据同步和备份的选择相当灵活，可以用iCloud也可以用dropbox等，反正数据就是文件而已

而后续程序改版为：

编辑以界面菜单操作为优先，虽然仍旧兼容部分markdown语法，但大幅阉割，完整的编写体验需要大量的UI操作
数据存储使用数据库sqlite，不再使用文件系统
dayone推出了自己的同步云服务，等于是变相把软件做成了订阅型软件，希望多端数据同步的必须买dayone自己的服务，不再可以使用第三方的iCloud之类的
限制单个post最多30张图片
单个图片文件分辨率上限为4K，大于4K则会被压到4K

导致了：

编辑体验非常难受，有种回到了被word支配的年代的感觉
备份比较麻烦，内容不够直观
因为引入了数据库的原因，很多数据的关系就不再直白了，必须理解数据库表和数据的关系才能掌握
- post和tag的关系，哪篇post有多少tag
- post和附件的关系，哪篇post有多少图片，图片在哪
这样的改版也造成后续软件切换有非常高的难度，因为不再是文件形式的数据保存，后续如果要换成其他软件，必须制作工具从数据库中导出数据才行
数据同步和数据安全都不再可选，且dayone的云服务早期非常不稳定
图片数量限制让人非常不愉快，特别是在做游记的时候

所以自dayone改版之后，一直有意向且在留意是否有比较好的工具可以转过去。

5. 个人感悟的工具选择

个人博客使用静态博客系统，剪藏笔记使用印象笔记，这个基本上不太需要动。但人生感悟这块数据太敏感了，而且太重要了，切不能随便交给一家厂商就完事了，一定要思考数据如何保证安全，如何保证在这家厂商服务关闭之后能简便切换到其他软件，阅读和编辑的连贯性。因此这块的工具选择有几点要求：

以markdown为优先的编写体验
以文件系统作为数据存储的方式
可以有一定的高级数据关系支持：分类、tagging、搜索
可以灵活切换到其他编辑软件
可以进行便利的备份

目前看下来只有obsidian能完全满足上述需求。

6. Obsidian

6.1 Obsidian简介

官方主页直接提供Desktop app的下载链接，也可以通过App Store安装。Mobile版本的下载在这里。

个人使用的是iPhone，所以使用对应的iOS app。这里推荐先下载iPhone app，然后使用mobile app在iCloud里创建Vault。如果反过来先使用Desktop app来创建Vault的话，在iCloud里会和mobile app存放在不同的位置，导致双端同步不一致。

该软件的app都是免费的，直接可以下载使用，而且完全没有广告：官方Pricing页面。个人用户是完全免费使用的。

其他有用的链接：

快捷键：Keyboard shortcuts
Search：Search
front matter：YAML front matter
第三方（社区）插件：Third-party plugins
- 浏览和安装第三方插件直接可以在obsidian内部完成，比较便捷，免去了下载软件包手动解压到指定位置的操作
- api doc：Obsidian API
- sample plugin repo：Obsidian Sample Plugin
必要插件：

obsidian的优点：

完全免费，和FSNotes这种号称免费但在mobile市场收费的货色不同，是真的免费
markdown优先的编辑模式，编辑/预览完全分离
纯文件模式进行数据管理，可以把它理解为一款代码编辑IDE，以纯文件夹形式管理posts
- TextBundle格式的官方支持尚未实装：TextBundle support
拥有插件机制，可以发挥社区能量，进行功能的丰富化
对一些批量操作支持非常优秀：
- post重命名可以同步修改Vault中所有post内对应的内链地址
- tag重命名也能同步修改Vault中所有post内对应的文本（需上面提到的插件支持）
搜索查询功能非常强大，可以做到从海量数据中找到需要查找的posts

当然obsidian也有缺点和问题，目前来看最大的问题是这款软件更偏向桌面，对mobile的支持较一般，特别是第三方插件，很多都是只针对桌面版进行了研发（上面提到的gallery插件就是）。

至少目前看来，这款软件是完全能满足我的需求的，甚至大大超出了我的预期。

6.3 Obsidian设置及使用

下面会简单介绍下如何设置及使用Obsidian，以桌面版为视角，之前也提到了mobile版本仍旧只是能用。

创建iCloud内Vault

之前也提到了，需要先使用Mobile app，按软件界面的要求设置Vault即可。这里需要记住创建出来的Vault文件夹的名字。

定位MAC上的文件夹位置

MAC上的数据是通过iCloud进行同步的，根据OS版本不同，位置可能会变动。目前我的OS是：

数据位置在：

$ pwd
/Users/Jonathan/Library/Mobile Documents/iCloud~md~obsidian/Documents
$ ll
total 0
drwxr-xr-x@  5 Jonathan  staff   160B  8 30 16:14 ./
drwxr-xr-x   4 Jonathan  staff   128B  8 26 15:22 ../
drwxr-xr-x@  2 Jonathan  staff    64B  8 28 19:51 .Trash/
drwxr-xr-x@ 10 Jonathan  staff   320B  8 27 21:54 .obsidian/
drwxr-xr-x@  5 Jonathan  staff   160B  8 30 16:14 Notes/
$ cd ./.obsidian
$ ll
total 48
drwxr-xr-x@ 10 Jonathan  staff   320B  8 27 21:54 ./
drwxr-xr-x@  5 Jonathan  staff   160B  8 30 16:14 ../
-rw-r--r--@  1 Jonathan  staff   281B  8 30 16:29 app.json
-rw-r--r--@  1 Jonathan  staff   102B  8 30 16:29 appearance.json
-rw-r--r--@  1 Jonathan  staff    42B  8 30 16:29 community-plugins.json
-rw-r--r--@  1 Jonathan  staff   249B  8 30 16:29 core-plugins.json
-rw-r--r--@  1 Jonathan  staff   837B  8 26 19:37 hotkeys.json
drwxr-xr-x@  4 Jonathan  staff   128B  8 27 14:59 plugins/
drwxr-xr-x@  3 Jonathan  staff    96B  8 26 16:30 themes/
-rw-r--r--@  1 Jonathan  staff   2.7K  8 30 16:29 workspace

这里我创建出来的Vault文件夹名字是Notes，可以看到在刚才的ll中存在。而Obsidian自己的数据（含配置、插件、主题等）则存放在.obsidian文件夹下，它是一个Vault一个专属的文件夹的，不存在global的设置。在有多个Vault需要共享同一份设置的时候会有点麻烦。

打开MAC上的Vault

打开MAC版的Obsidian，然后按界面上的按钮指引打开刚才提到的iCloud文件夹即可（到Documents那层）。

软件设置

点击界面最左下角的Settings按钮，打开设置界面。后续的设置按界面操作即可，这里把完成的设置内容作为json代码贴在这里。注意插件需要手动到第三方插件 > 社区插件浏览安装，搜索关键字为：gallery和tag。

app.json

{
  "showFrontmatter": true,
  "defaultViewMode": "preview",
  "showLineNumber": true,
  "useTab": false,
  "emacsyKeys": false,
  "newLinkFormat": "shortest",
  "alwaysUpdateLinks": true,
  "useMarkdownLinks": false,
  "attachmentFolderPath": "./",
  "readableLineLength": false
}

appearance.json

{
  "baseFontSize": 16,
  "theme": "obsidian",
  "translucency": true,
  "cssTheme": "Obsidian Nord"
}

community-plugins.json

[
  "obsidian-gallery",
  "tag-wrangler"
]

core-plugins.json

[
  "file-explorer",
  "global-search",
  "switcher",
  "graph",
  "backlink",
  "tag-pane",
  "page-preview",
  "note-composer",
  "command-palette",
  "markdown-importer",
  "outline",
  "word-count",
  "open-with-default-app",
  "file-recovery"
]

hotkeys.json

{
  "app:go-forward": [
    {
      "modifiers": [
        "Ctrl"
      ],
      "key": "Tab"
    }
  ],
  "app:go-back": [
    {
      "modifiers": [
        "Ctrl",
        "Shift"
      ],
      "key": "Tab"
    }
  ],
  "workspace:edit-file-title": [
    {
      "modifiers": [
        "Mod",
        "Shift"
      ],
      "key": "R"
    }
  ],
  "tag-pane:open": [
    {
      "modifiers": [
        "Mod",
        "Shift"
      ],
      "key": "T"
    }
  ],
  "outline:open-for-current": [
    {
      "modifiers": [
        "Mod",
        "Shift"
      ],
      "key": "O"
    }
  ],
  "workspace:export-pdf": [
    {
      "modifiers": [
        "Mod",
        "Shift"
      ],
      "key": "P"
    }
  ],
  "workspace:copy-url": [
    {
      "modifiers": [
        "Mod",
        "Shift"
      ],
      "key": "U"
    }
  ]
}

快捷键主要就几个：

打开设置：CMD + ,
编辑文件名：CMD + SHIFT + R
显示TAG面板：CMD + SHIFT + T
打开文件大纲：CMD + SHIFT + O
导出为PDF：CMD + SHIFT + P
前进：CTRL + TAB
后退：CTRL + SHIFT + TAB ，这两者保持和浏览器等的操作一致
复制Obsidian内部URL：CMD + SHIFT + U
切换编辑/预览模式：CMD + E
在所有文件中搜索：CMD + SHIFT + F
在当前文件中搜索：CMD + F
在当前文件中搜索并替换：CMD + OPT + F

使用

使用上和一般的MD编辑器没什么差别，使用CMD + E来切换编辑和预览模式。就几点需要注意下：

文件名不要直接在软件外重命名，而是一定要使用Obsidian来重命名，这样才能全部更新Vault内其他文件内对应的内链位置
同样的，重命名tag也一定要使用软件的插件功能来做
在文件的任何位置编写#TAG_NAME的文本，即可创建TAG_NAMEtag
~~gallery的配置使用如下~~
- ~~type：grid | active-thumb，一般使用grid，active-thumb为可拖拽的grid但有bug~~
- ~~path：存放会展示在gallery里的图片的路径~~
- ~~imgWidth：grid内每个图片格的宽度，一般不要太大~~
- ~~divWidth：%值，指grid所处的div占页面的宽度多少~~
- ~~divAlign：left | right，指grid所处的div在页面的左侧还是右侧~~
- ~~reverseOrder：true | false，是否逆转图片的展示顺序~~
- ~~customList：自定义的图片展示顺序：customList=5 10 2 4~~
post-gallery额配置使用如下
- name：在assets文件夹内，含图片的子文件夹名：assets/gallery00/*.jpg -> name: gallery00
- rowHeight：gallery内图片每行的高度，e.g 120
- margins：图片间的间距，e.g 5

e.g

name: gallery00
rowHeight: 200
margins: 5

6.4 Vault规划及front matter定义

Vault

由于Obsidian仅只是一款简单的编辑软件，和dayone这样使用数据库来管理数据的软件不同，它是不会对数据的存放位置和结构进行定义的，所有的一切都交由使用者自己组织。这就对使用者提出了要求，你不能随随便便把所有的内容全部都扔到Vault的根目录下，这会导致后续浏览及搜索的困难，也不能把所有的内容都分得过细或扔到过多层的子文件夹中，这也会导致浏览的障碍。

因此个人使用下面的格式来管理Vault：

iCloud Documents /
                 | .obsidian
                 | Notes /
                         | ...
                         | 2019 / ...
                         | 2020 / ...
                         | 2021 /
                                | ...
                                | 08 /
                                     | 20210828-obsidian-instruction /
                                                                     | assets / ... / *.jpg
                                                                     | obsidian-instruction.md

格式：Notes / YYYY / MM / YYYYMMDD-slug / slug.md | assets

Tag

posts文件都是分布在年月日的多层子文件夹下，因此直接通过文件系统进行浏览是非常困难的。这就要求尽量要做好post的tag内容管理，尽量分门别类做细，后面才可以通过tag的方式来进行post的快速浏览和查找。

e.g

#Tech #JavaScript
#Entertainment #Travel

个人Tag principles如下：

每个post都一定要有category定义，因为obsidian本身没有category功能，所以可以把category作为tag放到post里，方便后续搜索，e.g
- #Tech
- #Entertainment
- #Diary
每个post都一定要有3个维度的时间信息，e.g
- 年 #Y2021
- 月 #M202108 #M08
- 日 #D20210828 #D0828
- 因为obsidian规定tag必须以字母起始，所以必须加一个字符

其他的tag就可以按post本身内容自行定义即可。

Front matter

Obsidian本身对front matter基本上是完全不支持的，不解析其中的内容。但建议仍旧还是要做好front-matter的管理，录入一些原始数据，以便后续有新的plugin支持的时候，可以快速调整来生效。

个人使用如下的front matter内容：

uuid: "..."
path: "/2021/08/20210828-obsidian-instruction"
date: "2021-08-28"
slug: "obsidian-instruction"
title: "obsidian使用教程"
location:
  altitude: 1
  latitude: 38
  longitude: 128
  address: "南京东路XXX"
  placename: "XXX国际大酒店"
  district: "黄浦区"
  city: "上海市"
  province: "上海"
  country: "中国"
weather:
  temperature: 31
  humidity: 78
  weather: "晴"
  time: "13:33:27"
  aqi: 56

6.5 一些工具

agreatfool/dayone2md：将dayone的数据全部导出成上述文件夹格式md文件的命令行工具
agreatfool/obsidian-utils：帮助创建obsidian post的命令行工具，可以帮忙初始化title、tags、front-matter等信息
agreatfool/obsidian-post-gallery：专注于post内gallery展示的插件

SS订阅转Clash

Tue, 17 Aug 2021 02:02:22 GMT

1. 前言
2. 安装及使用

1. 前言

有点不记得当时为啥要使用这个转换工具了，应该是最早的ClashX不支持ShadowSocks协议导致我不得不使用工具来进行转换。不过我今天写这篇文章的时候看了下Clash的文档，貌似支持列表里已经有ShadowSocks了，不过因为我还没实际测试过，所以这个结论先保留下。

总之，之前因为Clash的支持原因，需要使用第三方工具将SS的订阅转换成Clash支持的格式然后Clash才能正常更新SS的订阅。具体就要使用到tindy2013/subconverter这个工具。因为之前找了好几次，所以这次留篇笔记来记录下，方便后续查找。

2. 安装及使用

安装

参照这篇指引来安装docker container：subconverter-docker

$ docker run -d --restart=always -p 25500:25500 tindy2013/subconverter:latest

使用

在Clash中输入下面的链接，来替代你自己机场的SS订阅链接：

http://127.0.0.1:25500/sub?target=clash&url=replace_this_with_your_ss_subscription_link&config=%CONFIG%

最后的config那块是可选的，我基本上不配置。对应的文档在：Advanced Usage。

How to do MySQL stress test

Tue, 20 Jul 2021 02:02:22 GMT

1. Foreword
- Scenario
2. DB Metrics
3. Determine Stress
4. Prepare SQL Statements
5. Prepare LUA script
6. Run the test
Others
- Optimize table
- Test the server io first
Reference
Appendix
- sysbench —help
- sysbench fileio help

1. Foreword

In this article we will go through how to do a RDBMS stress test using tool sysbench. In the article we are talking about MySQL, as sysbench also supports other DBs like PostgreSQL, you can replace MySQL with other DBs according to your requirement.

Scenario

Say we have a BE application like this:

It contains several application containers and several DB instances, each app would establish one connection to each DB instance.

Then we’d like to know under the target / high stress, what will happen to the DB instance, would they be able to handle the stress with ease or crash.

To figure out this, we can’t simply use a client process to send batch of duplicated SQL queries to DB instance. We need to mock the business like our BE app would do.

So several steps we need to do.

2. DB Metrics

First we need to figure out what’s the metrics we need to monitor in the stress test.

Basically:

MySQL instance CPU usage
MySQL instance Memory usage
MySQL connection amount
MySQL query amount
MySQL table lock wait: show status; -> table_locks_waited
MySQL innodb lock wait: show status like 'innodb_row_lock%'; -> innodb_row_lock_waits innodb_row_lock_time_avg
MySQL slow sql log
Host server CPU usage
Host server Memory usage
Host server io status: iostat -d -x -k 1, show device data show extend data show KB value refresh every 1 second
- %util 1-100, 100 means all io occupied
- svctm closing to await means almost no wait
- await > svctm means long io queue
- avgqu-sz : average queue size

For more metrics you may want to learn:

Run MySQL command: show status;
Download/View grafana dashboard: percona/grafana-dashboards

3. Determine Stress

In this step we need to figure out the expected stress level.

3 items to be determined:

How many records shall be in db table
How many connections
How’s the expected TPS

DB performance may fluctuate markedly according to the amount of records in table and amount of connections.

How (for example):

Records amount
- App users 100K
- Records of each user 5
- Total records amount: 100K * 5 = 500K
Connections amount
- BE pod amount -> connections amount
TPS
- Best is to see the production monitoring data, most real data
- Secondary is deducing, for example like
  - 1k online user
  - each user 1 api/sec
  - 1 api -> 1 transaction
  - 1k * 1tps = 1k tps

4. Prepare SQL Statements

In this step we need to figure out the SQL statements which would be used in the stress test.

How:

set up the staging backend server with monitoring, especially DB sql monitoring
run app with user-like actions
see the sql statements logged in binlog
pick top X statements of CRUD each type, like:
- SELECT: SQL1, SQL2, SQL3
- UPDATE: SQLa, SQLb, SQLc
also grab the CRUD ratio, like: 60% select 35% update 4% create 1% delete

5. Prepare LUA script

In this step we need to prepare the lua script which would be executed by the sysbench. There are multiple threads in sysbench, each thread will execute the LUA script rather than running SQL statement directly.

The script will:

determine every time execution which type of CRUD SQL should be executed, finally the CRUD ratio should be consistent with the percentage we got in step 4
select one SQL statement from the CRUD type SQL pool
execute the SQL

Using this LUA script we can mock the SQL executions just like the CRUD ratio we got in step 4, and SQLs are also we prepared in step 4.

LUA example:

function prepare()
    print("prepare of stress test")
end

function cleanup()
    print("cleanup of stress test")
end

function help()
    print("sysbench stress test; no special command line options available")
end

function thread_init(thread_id)
end

function thread_done(thread_id)
    db_disconnect()
end

function event(thread_id)

    -----------------------------------------------------------------------------------------------------------------------
    -- CONST
    -----------------------------------------------------------------------------------------------------------------------

    local SEARCH_KEY_PH = "^SK"
    local RANDOM_INT_PH = "^RI"

    -----------------------------------------------------------------------------------------------------------------------
    -- PARAMS
    -----------------------------------------------------------------------------------------------------------------------

    local totalRowsOfRecordsInDb = 10000

    local cmdSeed = {
        select = 3000,
        insert = 150,
        delete = 80,
        update = 6770
    }

    selectQueries = {}
    selectQueries["SELECT plantId, userId, seedId, status, growTime, harvestTime, blightTime, rarity, residue, leaf FROM fs2_plant_plants WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, finished FROM module_mission_finished WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, activityId, decorId, finished, acceptedRewards, expensePoint FROM fs2_activity_party WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, customerDefId, level, exp, rewards FROM fs2_customer_friendship WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, missionId, progress, acceptTime, expireTime FROM module_mission_in_progress WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, activityId, collect FROM fs2_activity_collect WHERE userId = ^SK;"] = 100
    selectQueries["SELECT userId, gridId, layer1Type, layer1, layer2Type, layer2, layer3Type, layer3 FROM fs2_grounds WHERE userId = ^SK;"] = 100
    selectQueries["SELECT decorId, decorDefId, userId, orient, cooldown, buildId, isUpgrade, effectCountLeft, resourceCountLeft, requestAccepted, output, withActivityOutput, freeMode FROM fs2_decoration WHERE userId = ^SK;"] = 100
    selectQueries["SELECT requestId, receiverId, senderId, helpId, type, info, time, expire, platformRequestId FROM fs2_social_request WHERE receiverId = ^SK;"] = 100
    selectQueries["SELECT userId, customerDefIds FROM fs2_customer_event WHERE userId = ^SK;"] = 100


    insertQueries = {}
    insertQueries["insert into `fv_dev`.`fs2_pet` ( `status`, `userId`, `fodderId`, `feedUpCount`, `feedUpTime`, `petDefId`) values ( '0', '89', '780003', '1', '1438223373', '900001');"] = 100
    insertQueries["insert into fs2_plant_plants (userId,seedId,status,growTime,harvestTime,blightTime,rarity,residue,leaf,soilId,soilType,soilCount,harvestCount,wood,requestAccepted,withActivityOutput) values ('57332', '110001', '1', '1428746759', '1428746819', '1429005959', '0', '0', '0', '0', '0', '0', '0', '0', null, null); "]=100


    updateQueries = {}
    updateQueries["UPDATE module_achievement_in_progress SET progress = '[3333333333,44444,5555555555555,7777777777777777777777,^RI,111111111111,22222222222222222222,999999999999999999999999,00000000]' WHERE userId = ^SK;"] = 1000
    updateQueries["UPDATE module_profile_infos SET info = ^RI, time = ^RI WHERE userId = ^SK;"] = 700
    updateQueries["UPDATE fs2_plant_plants SET seedId = ^RI, status = ^RI, growTime = ^RI, harvestTime = ^RI, blightTime = ^RI, rarity = ^RI, leaf = ^RI, residue = ^RI WHERE plantId = ^SK;"] = 700
    updateQueries["UPDATE module_profile SET  exp = exp + 1 WHERE userId = ^SK;"] = 500
    updateQueries["UPDATE module_mission_in_progress SET progress = '[3333333333,44444,5555555555555,7777777777777777777777,^RI,111111111111,22222222222222222222,999999999999999999999999,00000000]', acceptTime = ^RI WHERE userId = ^SK;"] = 300
    updateQueries["UPDATE module_item SET  updateTime = ^RI WHERE userId = ^SK;"] = 700
    updateQueries["UPDATE fs2_plant_seeds SET exp = ^RI WHERE userId = ^SK;"] = 100
    updateQueries["UPDATE fs2_social_feed SET helpId = ^RI, status = ^RI WHERE userId = ^SK;"] = 100
    updateQueries["UPDATE fs2_pet SET feedUpCount = ^RI, feedUpTime = ^RI, status = ^RI WHERE petId = ^SK;"] = 100
    updateQueries["UPDATE fs2_customer SET exp = ^RI, status = ^RI WHERE userId = ^SK;"] = 50
    updateQueries["UPDATE fs2_customer_town SET missionId = ^RI, leaveTime = ^RI WHERE customerId = ^SK;"] = 300
    updateQueries["UPDATE fs2_activity SET count = ^RI, status = ^RI WHERE userId = ^SK;"] = 100

    deleteQueries = {}
    deleteQueries["delete from fs2_plant_plants where userId=57332 limit 1;"] = 500
    deleteQueries["delete from fs2_pet where userId=89 limit 1;"] =500

    -----------------------------------------------------------------------------------------------------------------------
    -- LIB
    -----------------------------------------------------------------------------------------------------------------------

    local function randItem(seedTable)
        local result = 0

        local seedSum = 0
        for key, value in pairs(seedTable) do
            seedSum = seedSum + value
        end

        local randSeed = sb_rand(1, seedSum)

        local sum = 0

        for cmdType, prob in pairs(seedTable) do
            sum = sum + prob
            if randSeed <= sum then
                result = cmdType
            break end
        end



        return result
    end

    local function processSleep()
        os.execute("sleep 0.01") -- 10ms
    end

    -----------------------------------------------------------------------------------------------------------------------
    -- EXEC
    -----------------------------------------------------------------------------------------------------------------------

    local cmdType = randItem(cmdSeed)
    --print(cmdType)

    --if cmdType == "insert" or cmdType == "delete" then
    --    cmdType = "update"
    --end

    local querySeed = _G[cmdType .. "Queries"]
    
    local sql = randItem(querySeed)
    --print(sql)

    if cmdType == "update" then
        sql = sql:gsub("%^RI", sb_rand(1, totalRowsOfRecordsInDb))
    end
    sql = sql:gsub("%^SK", sb_rand(1, totalRowsOfRecordsInDb))

    --processSleep() -- let the lua script sleep to make qps lower for testing, if necessary

    db_query(sql)

end

You may find a sleep function processSleep, in old sysbench version there is no way to control the TPS speed, so this function could help to slow down the execution. In latest versions, sysbench provided the option to control tps, so it’s no longer necessary.

6. Run the test

In this step we will see how to run sysbench to execute the stress test.

$ sysbench --version
sysbench 1.0.18

Several useful options:

--threads : How many thread running inside the sysbench, each thread means a db connection
--rate : TPS, 0 means no limit, query as fast as possible
--events : Total requests to be made in the whole stress test, use this or --time
--time : How long should the stress test last, in seconds, use this or --events

Steps to run the stress test:

Start the MySQL instance along with all the monitoring facilities
Create database and table with schema SQL
Create the initial records in the db table
Run sysbench with low threads and rate, to warm up the MySQL instance (cache, index, etc…)
Run sysbench with target rate
See monitoring, check the CPU Memory iostat and lock waiting

$ sysbench \
  --threads=128 \
  --rate=300 \
  --time=3600 \
  --percentile=99 \
  --report-interval=5 \
  --db-driver=mysql \
  --mysql... \
  ./test_strategy.lua \
  run

After the test, see the monitoring system to grab the conclusion. Or may be need to analyse the cause of the performance issues.

Others

Optimize table

Use OPTIMIZE TABLE to resort index to restore the performance. After a lot of CRUD, the InnoDB index may be messed up, and the performance reduced. You can perform this command between several rounds of tests.

For InnoDB tables, optimize table will simply perform an alter table to reclaim the space.
If you have indexes, it will also resort the index pages, and update the statistics.

OPTIMIZE TABLE XXX;

Test the server io first

You may need to test the server io before test db, since the io of some cloud servers is not the same as claimed. You can still use sysbench to do it.

Create test file:

$ sysbench \
  --file-num=4 \
  --file-block-size=8k \
  --file-total-size=4G \
  --file-test-mode=rndrd \
  --file-extra-flags=direct \
  --max-requests=0 \
  --time=1200 \
  --threads=4 \
  fileio prepare

Test random read performance:

$ sysbench \
  --file-num=4 \
  --file-block-size=8k \
  --file-total-size=4G \
  --file-test-mode=rndrd \
  --file-extra-flags=direct \
  --max-requests=0 \
  --time=30 \
  --threads=4 \
  --report-interval=3 \
  fileio run

Reference

Appendix

sysbench —help

$ sysbench --help
Usage:
  sysbench [options]... [testname] [command]

Commands implemented by most tests: prepare run cleanup help

General options:
  --threads=N                     number of threads to use [1]
  --events=N                      limit for total number of events [0]
  --time=N                        limit for total execution time in seconds [10]
  --forced-shutdown=STRING        number of seconds to wait after the --time limit before forcing shutdown, or 'off' to disable [off]
  --thread-stack-size=SIZE        size of stack per thread [64K]
  --rate=N                        average transactions rate. 0 for unlimited rate [0]
  --report-interval=N             periodically report intermediate statistics with a specified interval in seconds. 0 disables intermediate reports [0]
  --report-checkpoints=[LIST,...] dump full statistics and reset all counters at specified points in time. The argument is a list of comma-separated values representing the amount of time in seconds elapsed from start of test when report checkpoint(s) must be performed. Report checkpoints are off by default. []
  --debug[=on|off]                print more debugging info [off]
  --validate[=on|off]             perform validation checks where possible [off]
  --help[=on|off]                 print help and exit [off]
  --version[=on|off]              print version and exit [off]
  --config-file=FILENAME          File containing command line options
  --tx-rate=N                     deprecated alias for --rate [0]
  --max-requests=N                deprecated alias for --events [0]
  --max-time=N                    deprecated alias for --time [0]
  --num-threads=N                 deprecated alias for --threads [1]

Pseudo-Random Numbers Generator options:
  --rand-type=STRING random numbers distribution {uniform,gaussian,special,pareto} [special]
  --rand-spec-iter=N number of iterations used for numbers generation [12]
  --rand-spec-pct=N  percentage of values to be treated as 'special' (for special distribution) [1]
  --rand-spec-res=N  percentage of 'special' values to use (for special distribution) [75]
  --rand-seed=N      seed for random number generator. When 0, the current time is used as a RNG seed. [0]
  --rand-pareto-h=N  parameter h for pareto distribution [0.2]

Log options:
  --verbosity=N verbosity level {5 - debug, 0 - only critical messages} [3]

  --percentile=N       percentile to calculate in latency statistics (1-100). Use the special value of 0 to disable percentile calculations [95]
  --histogram[=on|off] print latency histogram in report [off]

General database options:

  --db-driver=STRING  specifies database driver to use ('help' to get list of available drivers) [mysql]
  --db-ps-mode=STRING prepared statements usage mode {auto, disable} [auto]
  --db-debug[=on|off] print database-specific debug information [off]


Compiled-in database drivers:
  mysql - MySQL driver

mysql options:
  --mysql-host=[LIST,...]          MySQL server host [localhost]
  --mysql-port=[LIST,...]          MySQL server port [3306]
  --mysql-socket=[LIST,...]        MySQL socket
  --mysql-user=STRING              MySQL user [sbtest]
  --mysql-password=STRING          MySQL password []
  --mysql-db=STRING                MySQL database name [sbtest]
  --mysql-ssl[=on|off]             use SSL connections, if available in the client library [off]
  --mysql-ssl-cipher=STRING        use specific cipher for SSL connections []
  --mysql-compression[=on|off]     use compression, if available in the client library [off]
  --mysql-debug[=on|off]           trace all client library calls [off]
  --mysql-ignore-errors=[LIST,...] list of errors to ignore, or "all" [1213,1020,1205]
  --mysql-dry-run[=on|off]         Dry run, pretend that all MySQL client API calls are successful without executing them [off]

Compiled-in tests:
  fileio - File I/O test
  cpu - CPU performance test
  memory - Memory functions speed test
  threads - Threads subsystem performance test
  mutex - Mutex performance test

See 'sysbench <testname> help' for a list of options for each test.

sysbench fileio help

$ sysbench fileio help
sysbench 1.0.18 (using bundled LuaJIT 2.1.0-beta2)

fileio options:
  --file-num=N                  number of files to create [128]
  --file-block-size=N           block size to use in all IO operations [16384]
  --file-total-size=SIZE        total size of files to create [2G]
  --file-test-mode=STRING       test mode {seqwr, seqrewr, seqrd, rndrd, rndwr, rndrw}
  --file-io-mode=STRING         file operations mode {sync,async,mmap} [sync]
  --file-extra-flags=[LIST,...] list of additional flags to use to open files {sync,dsync,direct} []
  --file-fsync-freq=N           do fsync() after this number of requests (0 - don't use fsync()) [100]
  --file-fsync-all[=on|off]     do fsync() after each write operation [off]
  --file-fsync-end[=on|off]     do fsync() at the end of test [on]
  --file-fsync-mode=STRING      which method to use for synchronization {fsync, fdatasync} [fsync]
  --file-merged-requests=N      merge at most this number of IO requests if possible (0 - don't merge) [0]
  --file-rw-ratio=N             reads/writes ratio for combined test [1.5]

NSQ Note

Thu, 31 Dec 2020 02:02:22 GMT

1. 前言
2. 简介
3. 入门使用
- 3.1 组件
- 3.2 监控
4. 细节深入
5. 使用范例

1. 前言

说到消息队列一般就会直接想起Kafka、Rocket、Rabbit之类的全功能消息队列。但实际上在应用程序制作的过程中，我们也很需要一些小而精巧的消息队列用来进行某些业务上的解耦，或者降低主业务的消耗、耗时等。类似于redis作者的这个：antirez / disque。其中Nsq就是一款非常小巧而实用的消息队列，特别是它还基于Go语言编写，特别符合性能要求以及当前云原生的大方向。

2. 简介

Nsq的官方网站在：nsq.io。

一些比较关键的文档位置：

Quick Start：快速上手使用
FEATURES & GUARANTEES：一些核心功能点，和需要注意的特性
FAQ
Performance：官方的性能测试指标
Design：Nsq的核心设计，应该是所有官方文档中最重要的一篇了
INTERNALS：一些Nsq内部实现相关的细节

此外，还有一份PPT，虽然年代比较久远了（2012年），但基本上把所有Nsq中比较重要的点都提及到了，如果需要快速过一遍的话，看这篇PPT也是个不错的选择：NSQ - NYC Golang Meetup。

3. 入门使用

快速入门可以查看官方文档：Quick Start。Node的npm包在：nsqjs。

3.1 组件

Nsq主要有3个组件：

nsqd：真正的消息队列服务进程，消息收发都是由客户端直接和nsqd沟通完成，没有任何第三方中间成员
nsqlookupd：消息队列的拓扑管理，主要负责：
- nsqd的注册，存活管理
- topic和channel的管理，所有的topic有哪些，分别分布在哪几个nsqd上lookupd都知道
- 客户端会先到lookupd上查询目标的topic，找到之后再与某个匹配的nsqd进行连接，最后收发消息
nsqadmin：管理界面，功能非常丰富

关于各组件的启动参数，以及HTTP的API，都可以在官方文档中找到。需要记住的只有一点，末尾为0的端口都是TCP端口，1的端口都是HTTP端口。

NSQD
NSQLOOKUPD
- Deletion and Tombstones
NSQADMIN
UTILITIES：一系列实用的Nsq工具组件
- nsq_stat
- nsq_tail
- nsq_to_file
- nsq_to_http
- nsq_to_nsq
- to_nsq

3.2 监控

作为go语言编写的组件，理所当然的Nsq的各组件会暴露HTTP的/debug/pprof终端，作为性能查询的输出终端。

4. 细节深入

接下来的章节，我会把所有我个人觉得比较重要的Nsq相关内容都列进去。

nsqd消息不持久

默认行为是所有收到的消息都存储在nsqd的内存中，且没有任何内建的replication机制。所以默认情况下，节点挂掉的话，消息会丢失，如果这种情况不可接受，就需要自己做一些机制来规避消息丢失。

--mem-queue-size参数可以限定存储在内存中的消息数量，如果超量，则会将后续的消息存储在磁盘上。将该值设置为0可以将消息全部存储在磁盘上。

at least once

消息消费失败或超时会requeue，并在后续重新进行分发，所以一条消息可能会被多次投递到client进行消费，以保证该消息确定被消费完毕。消费者需要做好幂等，否则一条消息可能会别重复消费多次。

消息的投递是无序的

nsqd只管将消息按顺序投递出去，但消息可能因为网络原因等导致最终消费的顺序和投递的顺序不一致。

nsqlookupd延迟

服务发现被设计为最终一致。在扩散的过程中，可能会有时间差。客户端会最终从nsqlookupd获得所有的topic信息。

测试应用中很可能出现的一情况就是：nsqlookupd上并没有任何topic消息，producer创建，nsqd上创建出topic，并在之后同步topic信息到nsqlookupd。而在这之前早得多consumer就已经连上nsqlookupd并没有收到任何topic的信息，这中间会有一个时间差。consumer会静止在那里，直到配置的lookup间隔时间到了，然后consumer会再次查询nsqlookupd，并最终或得到topic信息以及所属的nsqd。

可以看下这几个comment：

性能

看官方文档：Performance。

topic和channel

估计这是使用Nsq的程序员最初最难搞懂的东西。一般来说其他的消息队列都是将消息发布到topic中，然后多个consumer消费一个topic。但Nsq在topic和consumer之间还插入了一个channel的概念。

这里主要是看一个图：

需要理解的最重要的概念是，同一个topic下的所有channel，都会得到进入topic的消息的拷贝。同样一份消息，进入topic后会分别拷贝并进入每一个channel，每个channel都需要各自的consumer把消息消费掉，否则就会造成消息积压。

简单来说：如果你希望和一般的消息队列一样的 topic => consumers，那么就让所有该topic下的消费者使用同一个channel即可。

channel的设计让Nsq可以做一些其他消息队列做不到的用途，最为常见的是：消息广播。多个consumer都需要在某个业务触发的时候得到通知，那么就在某个topic下，让所有的consumer都定义一个自己的channel连接进去（topic_channel_node_1/…），这样所有的consumer都各自占据了一个channel，而所有的channel都会得到topic内消息的拷贝，所以他们会都得到同样的消息通知。

自动消失的topic和channel

topic和channel都是持久化的，默认情况下在创建成功后，他们都是不会自动消失的，时间长了之后清理就会比较麻烦。而上面的例子中那种类似消息通知的情况，其实topic和channel都是生命周期非常短暂的，一般我们希望他们在没用了之后就被销毁掉。

在topic和channel的名字后面添加#ephemeral可以做到这点，当所有连接在topic或channel上的producer/consumer都断开连接之后，nsqd就会自动删除该topic或channel。

需要注意的是，#ephemeral命名的topic/channel在超过--mem-queue-size的限制之后不会将消息写入磁盘，而是直接丢弃。这点行为上和普通的topic/channel非常不同，一定要小心注意。

max-in-flight

客户端可以设置该值（比如说10），然后客户端在连接到nsqd的时候会发送RDY 10过去，nsqd就会知道该client的同时处理能力。在接下来的消息推送过程中，nsqd会不断向该client推送消息，直到目前已分发且尚未反馈结果的消息数量达到该数值（10）为止。这是为了更好的性能，client程序如果实现了多线程的话，可以充分利用线程和CPU来消费消息，而不是只有一个线程在工作，其他的都在闲置。

对于node程序来说，这个数值就没有意义了，因为node进程只有一个工作线程。

还可以看下这个comment：Question about concurrency and Max in Flight #221。

减轻GC压力

见官方文档：Reducing GC Pressure。

消息生命周期

一条消息的生命周期（消费端）主要是控制在client手中，这点和普通的消息队列的设计理念完全不同，这里需要花点时间稍微整理下。

消息的创建是producer连接到nsqd，并进行publish的操作，这点没有任何问题。创建成功消息就收到了，失败的话，则消息在nsqd上不存在。

消息的消费由nsqd向连接的consumer进行推送：

消息已分发且尚未反馈（未到超时时间），状态：In-Flight
消息已分发且超时没有反馈（该超时的时长是在客户端设置的！），状态：Time Out，该消息会被nsqd重新requeue（REQ）
- 消息在处理中，且耗时很长，可以由客户端进行 Touch，这样该消息就不会Time Out
消息发送后，可以由客户端主动进行requeue（REQ）
- requeue行为可以附带设置延迟（Deferred）
消息发送后，如果客户端出错被认为是有问题的，客户端自身需要恢复，则客户端可以将该消息反馈为backoff，这个操作会导致：
- nsqd会将该消息requeue，消息本身会再次（如果设置延迟的话，也会Deferred）分发
- 此外这个操作会导致客户端将自身的RDY设置为0，意味着这个客户端短时间内将拒绝处理任何消息
消息发送后，如果该消息之前被requeue则该消息会附带Attempts（重试）数，客户端在尝试失败后，会匹配失败次数，如果超过限制，则该消息会被DISCARD，即客户端会直接将该消息标记为Finished（FIN）
- 如果客户端的max attempts设置为0，则可以无限次重试，不会被discard
消息发送后，可以由客户端标记为完成Finished（FIN）

可以看到Nsq的客户端有很大的权利，特别是失败重试的决策是由客户端做的，如果超限消息就会被丢弃，标记为完成。

更多关于Timeout相关，请见comment：Timeout options #1028。

关于requeue和backoff的详细分析，可以看这篇：NSQ Requeue and Backoff。

Admin Metrics

Admin统计数据里的一些词汇可以简单解释下：

Message Queues：

Depth：当前存储在内存和磁盘上的消息总量（尚未被分发）
In-Flight：目前已经被分发，但尚未被标记为完成（FIN）、重新入队（REQ）或是超时的消息总量
Deferred：目前被重新入队且显式标记为推迟处理并且尚未到重新分发阶段的消息总量

Statistics：

Requeued：消息因超时或被显式要求而重新入队的次数
Timed Out：消息因超过设定的超时时长未响应，而被标记为超时的次数
Messages：在节点启动之后收到的消息总数
Rate：过去两次statsd间隔间，每秒新收到的消息数量
Connections：连接总数

Client Connections：

NSQd Host：Address of the nsqd node this client is connected to.
In-flight：当前发送给该client等待返回的消息数量
Ready Count：当前client节点最高in-flight可能的消息数量
Finished：所有当前client节点标记为FIN的消息数量
Requeued：同上，REQ
Messages：所有发送给该client节点的消息数量

5. 使用范例

光说理论上的东西比较枯燥，实践操作也是比较重要的，下面可以通过几个例子来看下Nsq的一些行为。

pubBeforeSub

If there is no topic on nsqd (first execution), reader will suck for a long time. Since at the first time reader connect to lookupd, there hasn’t been updated with the published topics info yet. So it will suck until readers retrieve topics info next time.

pubBeforeSub:
    Two writers initialized
    Two writers publish 3 messages each into topic "TOPIC1" (total 6)
    One of the writer publish 1 message into topic "TOPIC2_UNI"
    Two readers created for topic "TOPIC1" with the same channel "TOPIC1_READER_CHANNEL"
    One reader created for topic "TOPIC2_UNI" with channel "TOPIC2_UNI#ephemeral"
    -
    Two readers share the total 6 messages in topic "TOPIC1"
    One reader consume the message in topic "TOPIC2_UNI"

➜  couchnsq git:(master) ✗ ./bash/nsq_run.sh
  Nsq:Writer:bgF6l bgF6l: ready +0ms
  Nsq:Writer:Plwtx Plwtx: ready +0ms
  Nsq:Reader:oiFQg oiFQg: nsqd connected: "10.10.2.126:4250" +0ms
  Nsq:Reader:oiFQg oiFQg: nsqd connected: "10.10.2.126:4150" +0ms
  Nsq:Reader:MmLbX MmLbX: nsqd connected: "10.10.2.126:4250" +0ms
  Nsq:Reader:MmLbX MmLbX: nsqd connected: "10.10.2.126:4150" +0ms
  Nsq:Reader:8hpju 8hpju: nsqd connected: "10.10.2.126:4250" +0ms
  Nsq:Reader:oiFQg oiFQg: message 0e38318eeb01e000 got: "{"msg":"TOPIC1:jQ77FfY8lS"}" +16ms
  Nsq:Message oiFQg: message 0e38318eeb01e000 respond: "0", "FIN 0e38318eeb01e000
  Nsq:Message " +0ms
  Nsq:Reader:MmLbX MmLbX: message 0e38318eeb01e001 got: "{"msg":"TOPIC1:ONvD8mH4Jq"}" +16ms
  Nsq:Message MmLbX: message 0e38318eeb01e001 respond: "0", "FIN 0e38318eeb01e001
  Nsq:Message " +1ms
  Nsq:Reader:8hpju 8hpju: ready +17ms
  Nsq:Reader:MmLbX MmLbX: message 0e38318eeb01e002 got: "{"msg":"TOPIC1:7xjankTlzU"}" +3ms
  Nsq:Message MmLbX: message 0e38318eeb01e002 respond: "0", "FIN 0e38318eeb01e002
  Nsq:Message " +3ms
  Nsq:Reader:oiFQg oiFQg: message 0e38318eeb435000 got: "{"msg":"TOPIC1:bQOiIt7BLE"}" +5ms
  Nsq:Message oiFQg: message 0e38318eeb435000 respond: "0", "FIN 0e38318eeb435000
  Nsq:Message " +1ms
  Nsq:Reader:8hpju 8hpju: message 0e38318eec435000 got: "{"msg":"TOPIC2_UNI:Ms10V0jtpc"}" +3ms
  Nsq:Message 8hpju: message 0e38318eec435000 respond: "0", "FIN 0e38318eec435000
  Nsq:Message " +1ms
  Nsq:Reader:MmLbX MmLbX: message 0e38318eeb435001 got: "{"msg":"TOPIC1:APZJDBiVP9"}" +3ms
  Nsq:Message MmLbX: message 0e38318eeb435001 respond: "0", "FIN 0e38318eeb435001
  Nsq:Message " +1ms
  Nsq:Reader:MmLbX MmLbX: message 0e38318eeb435002 got: "{"msg":"TOPIC1:CXF6AQVBDr"}" +53ms
  Nsq:Message MmLbX: message 0e38318eeb435002 respond: "0", "FIN 0e38318eeb435002
  Nsq:Message " +53ms
^C  Nsq:Writer:bgF6l bgF6l: closed +1m
  Nsq:Writer:Plwtx Plwtx: closed +1m
  Nsq:Reader:oiFQg oiFQg: notReady +26s
  Nsq:Reader:MmLbX MmLbX: notReady +25s
  Nsq:Reader:8hpju 8hpju: notReady +26s
NsqTest: all cleared

sameMessageMultiChannel

Multiple channels subscribe the same topic will receive duplicate messages.

sameMessageMultiChannel:
    Two writers initialized
    One of the writer publish 1 message into topic "TOPIC_SAME"
    Two readers created for topic "TOPIC_SAME" with two channels "TOPIC_SAME_CHANNEL_1/2" subscribe the same topic
    -
    Two readers receive the same message

➜  couchnsq git:(master) ✗ ./bash/nsq_run.sh
  Nsq:Writer:oeAOC oeAOC: ready +0ms
  Nsq:Writer:EdW9U EdW9U: ready +0ms
  Nsq:Reader:SuqpY SuqpY: nsqd connected: "10.10.2.126:4250" +0ms
  Nsq:Reader:vKCk9 vKCk9: nsqd connected: "10.10.2.126:4250" +0ms
  Nsq:Reader:vKCk9 vKCk9: ready +5ms
  Nsq:Reader:SuqpY SuqpY: ready +6ms
  Nsq:Reader:vKCk9 vKCk9: message 0e38322140035000 got: "{"msg":"TOPIC_SAME:Hn4tB5UA0N"}" +3ms
  Nsq:Message vKCk9: message 0e38322140035000 respond: "0", "FIN 0e38322140035000
  Nsq:Message " +0ms
  Nsq:Reader:SuqpY SuqpY: message 0e38322140035000 got: "{"msg":"TOPIC_SAME:Hn4tB5UA0N"}" +3ms
  Nsq:Message SuqpY: message 0e38322140035000 respond: "0", "FIN 0e38322140035000
  Nsq:Message " +0ms
^C  Nsq:Writer:oeAOC oeAOC: closed +3s
  Nsq:Writer:EdW9U EdW9U: closed +3s
  Nsq:Reader:vKCk9 vKCk9: notReady +3s
  Nsq:Reader:SuqpY SuqpY: notReady +3s
NsqTest: all cleared

subBeforePub

If the topic not deleted before execution (or first run). Reader will suck for a long time, the reason have been explained previously.

subBeforePub:
    Two writers initialized
    One reader create to subscribe an non-existing topic "TOPIC_UNKNOWN"
    One of the writer wait 1000ms, then publish 1 message into topic "TOPIC_UNKNOWN"
    -
    One reader wait for a long time then receive the message

➜  couchnsq git:(master) ✗ ./bash/nsq_run.sh
  Nsq:Writer:2Fr6p 2Fr6p: ready +0ms
  Nsq:Writer:vFIw5 vFIw5: ready +0ms
  Nsq:Reader:uR6Lp uR6Lp: nsqd connected: "10.10.2.126:4150" +0ms
  Nsq:Reader:uR6Lp uR6Lp: ready +5ms
  Nsq:Reader:uR6Lp uR6Lp: message 0e38323df741e000 got: "{"msg":"TOPIC_UNKNOWN:kCwBySUMY0"}" +984ms
  Nsq:Message uR6Lp: message 0e38323df741e000 respond: "0", "FIN 0e38323df741e000
  Nsq:Message " +0ms
^C  Nsq:Writer:2Fr6p 2Fr6p: closed +3s
  Nsq:Writer:vFIw5 vFIw5: closed +3s
  Nsq:Reader:uR6Lp uR6Lp: notReady +2s
NsqTest: all cleared

errorMessage

Send error message, and message would be requeue with backoff in the reader, finally it would be discarded (finished).

{
  "maxAttempts": 3
}

➜  couchnsq git:(master) ✗ ./bash/nsq_run.sh
  Nsq:Writer:5P9rd 5P9rd: ready +0ms
  Nsq:Writer:KKhyz KKhyz: ready +0ms
  Nsq:Reader:hSWmK hSWmK: nsqd connected: "10.10.2.126:4150" +0ms
  Nsq:Reader:hSWmK hSWmK: ready +5ms
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 got: "{"msg":"should throw error:WGZ9VlLLPa"}" +4ms
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 error & requeue, attempts: 1 +1ms
  Nsq:Message hSWmK: message 0e3832a5bb01e000 backoff +0ms
  Nsq:Message hSWmK: message 0e3832a5bb01e000 respond: "1", "REQ 0e3832a5bb01e000 2000
  Nsq:Message " +1ms
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 got: "{"msg":"should throw error:WGZ9VlLLPa"}" +4s
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 error & requeue, attempts: 2 +0ms
  Nsq:Message hSWmK: message 0e3832a5bb01e000 backoff +4s
  Nsq:Message hSWmK: message 0e3832a5bb01e000 respond: "1", "REQ 0e3832a5bb01e000 2000
  Nsq:Message " +0ms
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 got: "{"msg":"should throw error:WGZ9VlLLPa"}" +7s
  Nsq:Reader:hSWmK hSWmK: message 0e3832a5bb01e000 error & requeue, attempts: 3 +0ms
  Nsq:Message hSWmK: message 0e3832a5bb01e000 backoff +7s
  Nsq:Message hSWmK: message 0e3832a5bb01e000 respond: "1", "REQ 0e3832a5bb01e000 2000
  Nsq:Message " +0ms
  Nsq:Reader:hSWmK hSWmK: message discarded: "{"msg":"should throw error:WGZ9VlLLPa"}" +11s
^C  Nsq:Writer:5P9rd 5P9rd: closed +23s
  Nsq:Writer:KKhyz KKhyz: closed +23s
  Nsq:Reader:hSWmK hSWmK: notReady +2s
NsqTest: all cleared

使用frp内网穿透进行ssh登录

Mon, 19 Oct 2020 02:02:22 GMT

前言
架构与场景理解
安装
- 服务端
- 客户端
最终使用
Links

前言

内网穿透工具frp，有需要的人肯定已经了解它是什么了，不知道的可以去官网看下：

fatedier/frp

架构与场景理解

这块网上其实已经有相当多的文章进行过阐述了，这里就简单说一些我的理解。

首先需要明确角色：

用户：需要从外部（公网上）访问内部服务的人
frp服务端：处于公网上，拥有固定IP或者固定域名的主机；必须是主机，需要可以在这台主机上安装frp的服务端程序
frp客户端：处于内网上，缺失固定IP或者从公网上无法访问得到的一些局域网内主机；同样必须是主机，必须可以安装frp的客户端程序
内部服务：可以是和frp客户端安装在同一台主机上的应用程序，也可能是和frp客户端处于同一内网的某一台主机上的一些应用程序

如果内部服务这台主机在公网上可以直接访问得到，那么用户就可以直接过去访问，就没有frp什么事情了。但很多情况就是如此不尽如人意，某些服务和主机就是隐藏在一些内部私有的网络里面的，在公网上是没办法直接访问的。

这时候就需要在公网的主机上安装frp服务端程序，作为一个大家的目标（后续用户和frp客户端都会主动连接到这台主机上，这个主机是双向标的）。用户连接上来是为了访问内部服务，而frp客户端连接上来，则是为了告知frp服务端，内部服务到底在哪里。因为处于内网的服务，frp服务端也不能主动得知，必须frp客户端主动连接上去告知服务端，我在这里。

上面是一些比较感性的理解，具体的可以看图（注意图上的s和c，frps就是刚才说的frp服务端，而frpc则是frp客户端）：

安装

安装分为服务端和客户端两部分。frp在大部分的linux发行版本上都是没有的，所以一般需要直接从github上下载release包，具体可以到这里查看。

下面的例子都以ubuntu为例，应用场景都是：

用户 => frp服务端（公网） => frp客户端（私有网络） => 目标内部主机ssh（私有网络）

服务端

$ uname -m
x86_64
$ wget https://github.com/fatedier/frp/releases/download/v0.34.1/frp_0.34.1_linux_amd64.tar.gz
$ tar zxvf frp_0.34.1_linux_amd64.tar.gz
$ rm ./frp_0.34.1_linux_amd64.tar.gz
$ mv -f ./frp_0.34.1_linux_amd64 ./frp
$ cd frp
$ vim frps.ini

bind_port = 7000
token = some_secret_string
dashboard_port = 7500
dashboard_user = user_name
dashboard_pwd = user_password

说明：

bind_port：frp客户端连接frp服务端的端口号
token：frp客户端连接服务端需要一致的秘钥（客户端和服务端两者的ini配置文件里这个字串必须一致）
dashboard_port：frp服务端暴露出来，让管理员监控的面板的端口号
dashboard_user：监控面板的用户名
dashboard_pwd：监控面板的用户密码

接下来创建ubuntu的开机启动和daemon控制：

$ sudo vim /etc/systemd/system/frps.service

填写内容：

[Unit]
Description=frps daemon
After=syslog.target  network.target
Wants=network.target

[Service]
Type=simple
ExecStart=/path_to_frp/frps -c /path_to_frp/frps.ini
Restart= always
RestartSec=1min
ExecStop=/usr/bin/killall frps

[Install]
WantedBy=multi-user.target

启动、设置开机启动、重启，三个命令：

$ sudo systemctl start frps
$ sudo systemctl enable frps
$ sudo systemctl restart frps

客户端

$ uname -m
x86_64
$ wget https://github.com/fatedier/frp/releases/download/v0.34.1/frp_0.34.1_linux_amd64.tar.gz
$ tar zxvf frp_0.34.1_linux_amd64.tar.gz
$ rm ./frp_0.34.1_linux_amd64.tar.gz
$ mv -f ./frp_0.34.1_linux_amd64 ./frp
$ cd frp
$ vim frpc.ini

[common]
server_addr = some_ip
server_port = 7000
token = some_secret_string

[ssh]
type = tcp
local_ip = 127.0.0.1 
local_port = 22
remote_port = 6000

说明：

server_addr：frp服务端所在的机器的IP，也就是公网上的那台
server_port：这个端口号记得和之前服务端的配置一致
token：这个也必须和之前服务端的配置一致
local_port：内部服务所在那台机器，也就目标登录机的ssh端口号
remote_port：这个端口号，是指frpc的local_port应该映射到frps主机上的哪个端口号，也就是最终用户ssh登录时使用的端口号

仍旧需要创建ubuntu的开机启动和daemon控制：

$ sudo vim /etc/systemd/system/frpc.service

填写内容：

[Unit]
Description=frpc daemon
After=syslog.target  network.target
Wants=network.target

[Service]
Type=simple
ExecStart=/path_to_frp/frpc -c /path_to_frp/frpc.ini
Restart= always
RestartSec=1min
ExecStop=/usr/bin/killall frpc

[Install]
WantedBy=multi-user.target

启动、设置开机启动、重启，三个命令：

$ sudo systemctl start frpc
$ sudo systemctl enable frpc
$ sudo systemctl restart frpc

最终使用

最终用户ssh登录的时候，使用的命令如下：

$ ssh -v -p 6000 user@frps_ip

Links

使用proxychains进行命令行proxy设置

Mon, 19 Oct 2020 02:02:22 GMT

前言
安装
MAC下的SIP问题

前言

proxychains是一款相当好用的命令行命令proxy设置工具。一般来说使用ssh登录、curl、wget等一系列命令，有的时候都很需要进行proxy设置，理由么大家都懂的。这时候有像proxychains这样的工具就会非常方便。

官网：

rofl0r/proxychains-ng

安装

在MAC下安装仍旧非常简单：

$ brew update --verbose
$ brew install proxychains-ng --verbose

然后创建配置文件：

$ mkdir ~/.proxychains
$ vim ~/.proxychains/proxychains.conf

内容如下，其实也就没几条有用的：

# proxychains.conf  VER 4.x
#
#        HTTP, SOCKS4a, SOCKS5 tunneling proxifier with DNS.


# The option below identifies how the ProxyList is treated.
# only one option should be uncommented at time,
# otherwise the last appearing option will be accepted
#
dynamic_chain
#
# Dynamic - Each connection will be done via chained proxies
# all proxies chained in the order as they appear in the list
# at least one proxy must be online to play in chain
# (dead proxies are skipped)
# otherwise EINTR is returned to the app
#
#strict_chain
#
# Strict - Each connection will be done via chained proxies
# all proxies chained in the order as they appear in the list
# all proxies must be online to play in chain
# otherwise EINTR is returned to the app
#
#round_robin_chain
#
# Round Robin - Each connection will be done via chained proxies
# of chain_len length
# all proxies chained in the order as they appear in the list
# at least one proxy must be online to play in chain
# (dead proxies are skipped).
# the start of the current proxy chain is the proxy after the last
# proxy in the previously invoked proxy chain.
# if the end of the proxy chain is reached while looking for proxies
# start at the beginning again.
# otherwise EINTR is returned to the app
# These semantics are not guaranteed in a multithreaded environment.
#
#random_chain
#
# Random - Each connection will be done via random proxy
# (or proxy chain, see  chain_len) from the list.
# this option is good to test your IDS :)

# Make sense only if random_chain or round_robin_chain
#chain_len = 2

# Quiet mode (no output from library)
#quiet_mode

# Proxy DNS requests - no leak for DNS data
#proxy_dns

# set the class A subnet number to use for the internal remote DNS mapping
# we use the reserved 224.x.x.x range by default,
# if the proxified app does a DNS request, we will return an IP from that range.
# on further accesses to this ip we will send the saved DNS name to the proxy.
# in case some control-freak app checks the returned ip, and denies to
# connect, you can use another subnet, e.g. 10.x.x.x or 127.x.x.x.
# of course you should make sure that the proxified app does not need
# *real* access to this subnet.
# i.e. dont use the same subnet then in the localnet section
#remote_dns_subnet 127
#remote_dns_subnet 10
#remote_dns_subnet 224

# Some timeouts in milliseconds
tcp_read_time_out 15000
tcp_connect_time_out 8000

### Examples for localnet exclusion
## localnet ranges will *not* use a proxy to connect.
## Exclude connections to 192.168.1.0/24 with port 80
# localnet 192.168.1.0:80/255.255.255.0

## Exclude connections to 192.168.100.0/24
# localnet 192.168.100.0/255.255.255.0

## Exclude connections to ANYwhere with port 80
# localnet 0.0.0.0:80/0.0.0.0

## RFC5735 Loopback address range
## if you enable this, you have to make sure remote_dns_subnet is not 127
## you'll need to enable it if you want to use an application that
## connects to localhost.
# localnet 127.0.0.0/255.0.0.0

## RFC1918 Private Address Ranges
# localnet 10.0.0.0/255.0.0.0
# localnet 172.16.0.0/255.240.0.0
# localnet 192.168.0.0/255.255.0.0

# ProxyList format
#       type  ip  port [user pass]
#       (values separated by'tab'or'blank')
#
#       only numeric ipv4 addresses are valid
#
#
#        Examples:
#
#        socks5  192.168.67.78    1080    lamer    secret
#        http    192.168.89.3     8080    justu    hidden
#        socks4  192.168.1.49     1080
#        http    192.168.39.93    8080
#
#
#       proxy types: http, socks4, socks5
#        ( auth types supported:"basic"-http"user/pass"-socks )
#
[ProxyList]
# add proxy here ...
# meanwile
# defaults set to"tor"
socks5 127.0.0.1 6153
http 127.0.0.1 6152

这里需要注意，安装完之后的命令名为：proxychains4，而不是proxychains。

MAC下的SIP问题

MAC下如果使用proxychains来进行操作的话，会发现一些命令其实并没有生效。这里就会遇到一个SIP的问题，具体可以看：

Mac OSX 使用proxychains-ng

上面的处理方法是完全关闭SIP，这其实是不太可取的，这里还有另一个解决思路，见：

故事：试图不关闭 SIP 在 macOS Sierra 上使用 proxychains-ng

最后使用的命令会如下：

$ cp /usr/bin/ssh ~/Prog/Cmd
$
$ proxychains4 ~/Prog/Cmd/ssh -v -p 22 user@ip

Koa2 中间件范例

Thu, 02 Jul 2020 02:02:22 GMT

前言
中间件执行顺序
结论

前言

发现之前对koa的中间件的理解还不够完全，这里做点笔记。

中间件执行顺序

这里主要需要理解next函数。这个函数有几个点：

调用next函数，就会触发下一个中间件的业务逻辑执行（异步），但不会离开当前中间件，如果在next之后有逻辑代码的话，会正常执行
该函数调用是异步的，因此可以await等待后续的中间件执行结束返回回来
以next函数为分隔线，上面是顺序执行，下面是倒叙执行，上面的由上向下，下面的由下向上
next函数的显示执行构成了一个中间件的调用链，如果任何一个中间件没有调用next，则链条会在当前中间件中断，后续即便注册了再多的中间件也不会被执行

看几个例子：

洋葱式的调用顺序

app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("1a");
  await next();
  console.log("1b");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("2a");
  await next();
  console.log("2b");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("3a");
  await next();
  console.log("3b");
});

最后的输出是：

1a
2a
3a
3b
2b
1b

中断的链式调用

如果某个中间件没有调用next，则后续的调用链会中断。

app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("1a");
  await next();
  console.log("1b");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("2a");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("3a");
  await next();
  console.log("3b");
});

最后的输出是：

1a
2a
1b

不使用await

如果在调用next的时候不使用await的话，当前的中间件触发下一个中间件的执行（异步）后不会等待后续中间件返回，后续的业务逻辑会立即继续执行。会打乱洋葱回调的顺序。

app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("1a");
  await next();
  console.log("1b");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("2a");
  next();
  console.log("2b");
});
app.use(async (ctx: Koa.Context, next: Koa.Next) => {
  console.log("3a");
  await next();
  console.log("3b");
});

最后的输出是：

1a
2a
3a
2b
3b
1b

结论

主要有下面几点：

制作通用的中间件的时候，必须在代码中执行return next();将调用链继续下去，否则后面的中间件将会失效
一般编写中间件，如果某些业务需要等其他中间件执行结束后处理则使用await next();，否则一律return next();
next调用返回的是一个Promise，因此也可以使用next().catch之类的方式来进行错误处理

MaterialUI Notes

Wed, 10 Jun 2020 02:02:22 GMT

前言
Notes

前言

MaterialUI算是现在比较常见的UIKit了，用的人多，社区比较大，而且各种环境和框架的移植也很丰富，用起来比较简单和方便。当然使用的时候因为一些特有的概念和语法糖，还是需要一点上手时间。

官方的教程：Tutorial（基本上没用）。

一些资源：

Notes

样式

直接的样式处理及样式的编程，见文档：@material-ui/styles。简单范例：

import React from 'react';
import { makeStyles } from '@material-ui/core/styles';
import Button from '@material-ui/core/Button';

const useStyles = makeStyles({
  root: {
    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
    border: 0,
    borderRadius: 3,
    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .3)',
    color: 'white',
    height: 48,
    padding: '0 30px',
  },
});

export default function Hook() {
  const classes = useStyles();
  return <Button className={classes.root}>Hook</Button>;
}

栅格系统

栅格系统是布局的基础，官方文档在：Grid 栅格。当然，MaterialUI也提供了直接使用Flexbox来进行布局自定义的能力。另外，在做响应式布局的时候，Hidden组件也是非常重要的，能在某些分辨率下隐藏一些组件的显示。

栅格系统使用 Grid “盒子”组件实现：

为了达到高度的灵活性，盒子组件运用了用 CSS 的 Flexible Box 模块。
它有两种类型的布局：containers，items。
而项目宽度以百分比设置，因此相对于其父元素，它们总是流动的和变换大小的。
子元素则自带 padding 来和其他元素间隔。
你可以找到五个网格断点：xs，sm，md，lg 和 xl。

网格断点

首先需要了解响应式布局的网格断点，见文档：Breakpoints。要注意，虽然断点的尺寸是有预定义值的，但也是可以自定义改动的。

每个断点（一个键）匹配一个固定的屏幕宽度（一个值）：

xs，超小：0px
sm，小：600px
md，中等：960px
lg，大：1280px
xl，超大：1920px

value         |0px     600px    960px    1280px   1920px
key           |xs      sm       md       lg       xl
screen width  |--------|--------|--------|--------|-------->
range         |   xs   |   sm   |   md   |   lg   |   xl

// 样式的屏幕尺寸感知，并自适应
const styles = theme => ({
  root: {
    padding: theme.spacing(1),
    [theme.breakpoints.down('sm')]: {
      backgroundColor: theme.palette.secondary.main,
    },
    [theme.breakpoints.up('md')]: {
      backgroundColor: theme.palette.primary.main,
    },
    [theme.breakpoints.up('lg')]: {
      backgroundColor: green[500],
    },
  },
});

断点隐藏

一般在做响应式设计的时候，会用到Hidden组件，该组件有3组属性可以控制当前组件在某些断点情况下的显示和隐藏：

*Up：使用任何断点up属性的元素，给定的子节点将在断点以及断点以上时被隐藏。
*Down：使用任何断点down属性的元素，给定子节点将在断点以及断点以下时被隐藏。
*Only：利用断点only属性，给定子节点将被隐藏在指定的断点。

innerWidth  |xs      sm       md       lg       xl
            |--------|--------|--------|--------|-------->
width       |   xs   |   sm   |   md   |   lg   |   xl

smUp        |   show | hide
mdDown      |                     hide | show

看几个例子：

Up
*Up：使用任何断点up属性的元素，给定的子节点将在断点以及断点以上时被隐藏。playground：链接

<div className={classes.container}>
  <Hidden xsUp>
    <Paper className={classes.paper}>xsUp</Paper>
  </Hidden>
  <Hidden smUp>
    <Paper className={classes.paper}>smUp</Paper>
  </Hidden>
  <Hidden mdUp>
    <Paper className={classes.paper}>mdUp</Paper>
  </Hidden>
  <Hidden lgUp>
    <Paper className={classes.paper}>lgUp</Paper>
  </Hidden>
  <Hidden xlUp>
    <Paper className={classes.paper}>xlUp</Paper>
  </Hidden>
</div>

效果：

Down
*Down：使用任何断点down属性的元素，给定子节点将在断点以及断点以下时被隐藏。playground：链接

<div className={classes.container}>
  <Hidden xsDown>
    <Paper className={classes.paper}>xsDown</Paper>
  </Hidden>
  <Hidden smDown>
    <Paper className={classes.paper}>smDown</Paper>
  </Hidden>
  <Hidden mdDown>
    <Paper className={classes.paper}>mdDown</Paper>
  </Hidden>
  <Hidden lgDown>
    <Paper className={classes.paper}>lgDown</Paper>
  </Hidden>
  <Hidden xlDown>
    <Paper className={classes.paper}>xlDown</Paper>
  </Hidden>
</div>

效果：

Only
*Only：利用断点only属性，给定子节点将被隐藏在指定的断点。playground：链接

<div className={classes.container}>
  <Hidden only="lg">
    <Paper className={classes.paper}>Hidden on lg</Paper>
  </Hidden>
  <Hidden only="sm">
    <Paper className={classes.paper}>Hidden on sm</Paper>
  </Hidden>
  <Hidden only={['sm', 'lg']}>
    <Paper className={classes.paper}>Hidden on sm and lg</Paper>
  </Hidden>
</div>

效果：

流式网格

实际组件的空间占用布局是按Fluid grids 流式网格来排放的。举个例子：

import React from 'react';
import { makeStyles, createStyles, Theme } from '@material-ui/core/styles';
import Paper from '@material-ui/core/Paper';
import Grid from '@material-ui/core/Grid';

const useStyles = makeStyles((theme: Theme) =>
  createStyles({
    root: {
      flexGrow: 1,
    },
    paper: {
      padding: theme.spacing(2),
      textAlign: 'center',
      color: theme.palette.text.secondary,
    },
  }),
);

export default function CenteredGrid() {
  const classes = useStyles();

  return (
    <div className={classes.root}>
      <Grid container spacing={3}>
        <Grid item xs={12}>
          <Paper className={classes.paper}>xs=12</Paper>
        </Grid>
        <Grid item xs={6}>
          <Paper className={classes.paper}>xs=6</Paper>
        </Grid>
        <Grid item xs={6}>
          <Paper className={classes.paper}>xs=6</Paper>
        </Grid>
        <Grid item xs={3}>
          <Paper className={classes.paper}>xs=3</Paper>
        </Grid>
        <Grid item xs={3}>
          <Paper className={classes.paper}>xs=3</Paper>
        </Grid>
        <Grid item xs={3}>
          <Paper className={classes.paper}>xs=3</Paper>
        </Grid>
        <Grid item xs={3}>
          <Paper className={classes.paper}>xs=3</Paper>
        </Grid>
      </Grid>
    </div>
  );
}

效果：

例子中的xs是指前面提到的断点。只有屏幕尺寸在xs及其上的断点的情况下，才会按此布局。里面的数值是相对的，第一行最大值为12，后面第二行的6就是其一半。这个例子的playground：链接。

定义尺寸的时候可以对一个组件设置多个网格断点情况下的大小，这样做的话，可以让组件排布顺应不同的屏幕尺寸发生变化，看下面的例子：

例子中，在屏幕尺寸大于sm的情况下（从大到小匹配），sm的尺寸定义发挥作用：第二行的组件占比都为6，第二行2个组件各占一半，同样的第三行占比设为3，一行正好4个组件都放进去。

然后在屏幕尺寸缩小之后，尺寸小于sm，且大于xs，则xs的尺寸定义发挥作用：原来第二行各分一半的2个组件分别占了一行，原来第三行的4个组件分为了两行，每行两个。这个例子的playground：链接。

常用容器

Container

页面的主要容器，一般来说所有的内容都会放在Container内。Container的最大宽度，使用maxWidth来设置，里面的值需要设置刚才的断点值：xs、sm、md、lg、xl。另，Container的API文档，属性相关内容都在这里。

<Container maxWidth="sm" />

Box

包装容器，一般用来将某几个组件包装在一起做位置偏移或样式添加等操作。Box默认为一个div，也可以使用component来设置实际的HTML标签：

<Box component="span" m={1}>
  <Button />
</Box>

Grid

最基本的容器组件，通过将该组件相互嵌套使用，就可以组成非常复杂的页面布局。另，Grid的API文档，组件属性需要到这里查阅。

嵌套的情况下，container属性表示是包在外层的Grid，item则表示是从属于外层包装的Grid。如果有多层嵌套，则中间层的Grid既是container又是item。看个例子，playground在链接：

// defining FormRow
function FormRow() {
  return (
    <React.Fragment>
      <Grid item xs={4}>
        <Paper className={classes.paper}>item</Paper>
      </Grid>
      <Grid item xs={4}>
        <Paper className={classes.paper}>item</Paper>
      </Grid>
      <Grid item xs={4}>
        <Paper className={classes.paper}>item</Paper>
      </Grid>
    </React.Fragment>
  );
}

// using FormRow
<Grid container spacing={1}>
  <Grid container item xs={12} spacing={3}>
    <FormRow />
  </Grid>
  <Grid container item xs={12} spacing={3}>
    <FormRow />
  </Grid>
  <Grid container item xs={12} spacing={3}>
    <FormRow />
  </Grid>
</Grid>

效果：

间距设置

在MaterialUI中设置间距有已经做好的语法糖，直接使用即可，文档：Spacing，还有Theme Spacing。

其中属性是其中之一：

m - 对于设置margin
p - 对于设置padding

哪边边是其中之一：

t - 对于设置* margin-top或padding-top*的类
b - 对于设置margin-bottom的类或padding-bottom的类
l - 对于设置margin-left或padding-left的类
r - 对于设置margin-right或padding-right的类
x - 对于设置* -left和* -right的类
y - 对于设置* -top和* -bottom的类
空白 - 用于在元素的所有4个边上设置边距或填充的类

上面提到的属性的值，是数字，意思是几份。比如说my={1}就是上下添加一份的margin。下面的例子中，一份就是8px（MaterialUI的默认值一份就是8px）。

const theme = {
  spacing: 8,
}

<Box m={-2} />  // margin: -16px;
<Box m={0} />   // margin: 0px;
<Box m={0.5} /> // margin: 4px;
<Box m={2} />   // margin: 16px;

宽高尺寸设置

见文档：Sizing。

<Box width={1/4} /> // Numbers in [0,1] are multiplied by 100 and converted to % values.
<Box width={300} /> // Numbers are converted to pixel values.
<Box width="75%" /> // String values are used as raw CSS.
<Box width={1} />   // 100%

颜色系统

MaterialUI提供了配色相关的解决方案，见：Color 颜色（如果需要选择颜色代码的话，就直接在这个文档页面上查找），以及Theme Palette，以及Palette 调色。

<Box color="warning.main" />
<Box bgcolor="info.main" />

阴影

MaterialUI的阴影直接使用属性boxShadow就能实现了，文档：Shadow。

<Box boxShadow={1} />

层级

有时候一些元素会在同位置上进行重叠，这时候就需要确定它们的层级来进行相互覆盖的定义。在CSS中我们会使用z-index来操作，在MaterialUI中，一般使用属性zIndex来操作，且MaterialUI已经定义了一些，一般直接使用即可，范例：

<Box zIndex="tooltip" />
<Box zIndex="modal" />

预定义数值：

mobile stepper（移动设备起步）: 1000
speed dial: 1050
app bar（应用栏）：1100
drawer（抽屉）：1200
modal（浮层）：1300
snackbar：1400
tooltip（提示）：1500

文字铸排

组件内文字内容的Typography，MaterialUI有属性可以直接控制，不需要手动编写CSS。见文档：Typography，以及Theme Typography。

<Box textAlign="left" />                // right, left, center
<Box fontWeight="fontWeightRegular" />  // light, regular, medium, 500, bold
<Box fontSize="fontSize" />             // default, h6.fontSize, 16
<Box fontStyle="normal" />              // normal, italic, oblique
<Box letterSpacing={6} />               // 字符间距，这里的数值就是6px
<Box lineHeight="normal" />             // normal, 10

如果需要在页面上直接展示文字，建议使用组件Typography，见文档：Typography。此外，还有API文档，组件的属性需要到这里查阅。

看一个例子，该例子的playground在：链接。

<Grid item xs={12} sm container>
  <Grid item xs container direction="column" spacing={2}>
    <Grid item xs>
      <Typography gutterBottom variant="subtitle1">
        Standard license
      </Typography>
      <Typography variant="body2" gutterBottom>
        Full resolution 1920x1080 • JPEG
      </Typography>
      <Typography variant="body2" color="textSecondary">
        ID: 1030114
      </Typography>
    </Grid>
    <Grid item>
      <Typography variant="body2" style={{ cursor: 'pointer' }}>
        Remove
      </Typography>
    </Grid>
  </Grid>
  <Grid item>
    <Typography variant="subtitle1">$19.00</Typography>
  </Grid>
</Grid>

效果：

该组件的noWrap属性默认值为false，也就是说遇到文字过长的情况下会进行回行。如果将这个属性设置为true，则文字过长的部分会被截断，并显示为省略号。

统一风格系统

MaterialUI有一套统一的设计方案，方便开发者在App级别对所有的组件进行统一的样式及风格定义。官方文档：@material-ui/system。一般来说项目大的话，肯定有需要进行这部分的调整。如果使用的是官方Store中的一些Template，一般它们已经做好了对应的功能。

这部分比较庞大，细节很多。这里放一个简单例子，直观感受下：

import React from 'react'
import { ThemeProvider } from 'styled-components'

const theme = {
  spacing: 4,
  palette: {
    primary: '#007bff',
  },
};

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* children */}
    </ThemeProvider>
  )
}

更多的细节可以查看MaterialUI的Customization个性化文档。

Typescript

MaterialUI对Typescript支持很好，官方文档：TypeScript。里面细节还是有点多的，需要慢慢习惯用法。

Next.js Notes

Tue, 09 Jun 2020 02:02:22 GMT

0. 前言
1. 文件结构
2. 路由
4. SSR CSR Static
5. Next.js的其他知识点
6. React相关概念
- 6.1 state
- 6.2 effect
7. 自定义服务器
8. 问题及解决
- 8.1 TypeORM
资料

0. 前言

最近在尝试使用Next.js，虽说比直接裸用react简单不少，但还是有不少自有的特殊概念，因此这里开篇笔记，做下记录。

入门Next.js可以阅读官方的教程：Create a Next.js App。关于Next.js的优势，为什么要使用Next.js以及很多关于Next.js的细节等，可以查看这篇博文：The Next.js Handbook。

version9.4.4已知问题（会列一些对使用有影响的）：

trailing slash in link … 404 … #5214

1. 文件结构

默认被占用的路径只有两个：

project_root/pages：用来作为页面路由使用
project_root/public：用来进行静态文件输出

2. 路由

路由部分Next.js做了简化，默认是使用文件夹的形式，在project_root/pages/name.js|tsx下的文件，会映射为your_site/name这个路径，见官方文档：Pages。这样使用上非常简便，正常使用的话，就完全不需要引入第三方的类库（类似于react-router），也不需要使用编程的方式在代码中定义路由。更多细节：Routing

但上述的路由不能很好支持your_site/user/:user_id这样的需求。类似这样的需求在Next.js中也有解决方案，被称为dynamic route。官方文档在：Dynamic Routes。只需要把page文件的名字定义为：pages/post/[pid].js就OK。多参数的路径，类似：pages/post/[pid]/[comment].js，也是一样处理，这种路径在query参数中获取到的object就会含有多个键。

如果需要编程的方式来进行route操作的话，见文档：next/router。如果官方以文件夹形式管理的自动化route无法满足需求的话，还有功能强大的插件形式的route可以使用：Dynamic Routes for Next.js。

4. SSR CSR Static

Next.js默认支持了服务端渲染等提升前端获取速度和渲染性能的功能，但这也要求开发者必须谨慎对待组件的初始化和生命周期，因为显然运行在服务端和客户端的代码在获取组件初始化需要的数据时的方法是不一样的。

这部分的文档在：Data fetching，以及Automatic Static Optimization。

如果一个Page里getServerSideProps或getInitialProps存在的话，该Page就会被识别为服务端渲染（SSR），会在每次请求的时候进行渲染。而如果这两者皆不存在的话，该页面就会在服务器启动并构建的时候生成静态页面，后续每次请求的时候都会直接返回该静态页面。此外，在DEV模式的情况下，即便是静态渲染的Page也会在每次请求的时候触发渲染，需要注意。

主要方法有以下几个：

getStaticPaths

这个方法一般是配合dynamic route进行使用，会在Next.js服务器启动，并进行服务器静态构建的时候运行。其作用是告诉后续的getStaticProps某个动态路径的可能项。如果这个page你不需要静态构建，或者这个page也不是dynamic route，那就不需要实现这个函数。

举例来说pages/user/[id].js代码中的getStaticProps就需要返回：

export async function getStaticPaths() {
  return {
    paths: [
      { params: { id: '1' } },
      { params: { id: '2' } }
    ],
    fallback: true or false
  };
}

paths和fallback都是必须的键。fallback的意思是，当遇到客户端访问到一个并不存在于启动构建时制作的paths列表里的路径，Next.js应该允许客户端继续访问，还是直接返回一个404。这里要注意，如果fallback为true，也就是允许客户端继续访问的话，page代码一定要做好容错性，否则很容易导致页面报错。

getStaticProps

这个方法也是在Next.js服务器启动的时候，进行服务器静态构建的时候运行。其作用是用来给静态生成的页面提供props。同样的，如果这个page你不需要静态构建，那就不需要实现这个函数。

export async function getStaticProps(context) {
  return {
    props: {}, // will be passed to the page component as props
  }
}

如果是dynamic route的情况，该函数的context会包含getStaticPaths提供的路径信息：context.params = { id: '1' }。

getServerSideProps

同样是运行在服务器端，但并不是在Next.js构建时候运行，而是在每一次单独的请求到达的时候触发。

export async function getServerSideProps(context) {
  return {
    props: {}, // will be passed to the page component as props
  }
}

getInitialProps

基本上已弃用，如果是静态生成页面的话，使用getStaticProps；如果是服务端渲染的话，使用getServerSideProps。如果仅只是客户端渲染的页面，则使用React的effect就可以了。

5. Next.js的其他知识点

5.1 CSS相关

官方文档：Built-In CSS Support。

Next.js的CSS有很多细节，最主要的是命名后缀的问题，使用*.module.css的话，生成出来的页面上的CSS是会附带随机后缀的，就不会造成冲突。而如果需要引入global的css的话，则需要创建pages/_app.js文件，在这里修改。

jsx支持相关可以查阅这篇文档：styled-jsx。

5.2 变量配置

环境变量的官方文档：Environment Variables。

Next.js默认直接支持环境变量配置。基本上有配置相关需求就直接使用这个解决方案就OK了。

5.3 API后端

之前提到的route都是pages下的页面，一般来说还需要前后端交互使用的/api/*，这个在Next.js中被称为：API Routes。

5.4 自定义App

创建pages/_app.js代码文件，就可以在里面进行一些应用级别的初始化工作。官方文档：Custom App。自定义App的可能需求为：

Persisting layout between page changes
Keeping state when navigating pages
Custom error handling using componentDidCatch
Inject additional data into pages
Add global CSS

可能的应用场景：准备全局变量。在一款WEB应用中，某些数据是所有的页面都会有需求的，比如说当前session的最基本用户信息和权限信息等。而_app是所有的页面的基本入口，每个页面的渲染都会先经过它，那么其实就可以在这个代码中做这些事情。

页面渲染的先后顺序：

// Resolution order
//
// On the server:
// 1. app.getInitialProps
// 2. page.getInitialProps
// 3. document.getInitialProps
// 4. app.render
// 5. page.render
// 6. document.render
//
// On the server with error:
// 1. document.getInitialProps
// 2. app.render
// 3. page.render
// 4. document.render
//
// On the client
// 1. app.getInitialProps
// 2. page.getInitialProps
// 3. app.render
// 4. page.render

// _app.tsx
import App, {AppContext} from "next/app";

export type AppPageProps = AppProps & {
  your_global_page_props: any;
};

MyApp.getInitialProps = async (appCtx: AppContext) => {
    const appProps = await App.getInitialProps(appCtx);
    appProps.pageProps = {
        your_global_page_props: "",
    } as AppPageProps;

    return {...appProps};
};

// yourpage.tsx
import {AppPageProps} from "../_app";

export type YourPageProps = AppPageProps & {};

export default function YourPage(props: YourPageProps) {
    console.log(props); // { your_global_page_props: "" }
}

5.5 自定义Document

创建pages/_document.js代码文件，就可以在里面改动全局的<html>和<body>。官方文档：Custom Document。

6. React相关概念

Next.js和React的关系还是比较简单的。React本身的功能其实很简单，它就只是一个渲染引擎，而用来做应用的时候，你除了渲染之外还需要很多东西，而这些，React是给不了你的，必须你自己去组织。比如说最基本的请求路由，比如说打包用的webpack，比如说js transformation的babel，以及提升整体性能的服务端渲染和静态生成等等等等。

Next.js实际上就是在React的基础上，提供这些做应用必须的组件和功能之后的框架库。所以在使用Next.js进行开发的时候，React的知识也是必须的，否则就无法正确处理渲染相关的问题了。作为基本的使用者，React其实只有3大组的概念是必须要厘清楚的。

6.1 state

React的官方文档在：Using the State Hook。主要代码其实就只有一句：

const [count, setCount] = useState(0);

useState函数接受一个状态的默认值，然后返回一个数组，数组的0位是state变量，1位是改变这个state变量的方法，名字可以自己命名。

State的值调整需要注意内存的问题，有的时候不是仅仅只是修改对象的值就可以了。特别是遇到复杂的state，一个object或者数组里有嵌套的object和数组的时候，需要非常注意内存拷贝的问题。具体的可以看这个帖子：React: how to update state.item[1] in state using setState?。

6.2 effect

React的官方文档在：Using the Effect Hook - React。只要是涉及到状态变化的，都属于effect的范畴。一个React组件里可以使用useEffect函数注册多个effect事件。第二个参数的指定可以决定该effect事件应该在什么时候触发。

[]，效果同componentDidMount，仅只在组件mount的时候触发一次。同时，在这种effect中提供一个回调函数返回，则等同于componentWillUnmount，这个回调函数会在组件被unmount的时候被触发，用来做析构。

useEffect(() => {
  // your effect here
  return () => {}; // unmount
}, []);

无参数，效果同componentDidUpdate，每次组件re-render都会触发。

useEffect(() => {
  // your effect here
}); // no optional argument

[foo]，在数组中放入prop或state，则该effect只会在这个prop或state发生变化的时候触发。这个数组里可以放入复数的变量，表示监听多个变量的变化，任何一个发生变化都会触发该effect。

useEffect(() => {
  // your effect here
}, [foo]);

7. 自定义服务器

在大部分情况下，使用next [start]命令启动的服务器就已经足够满足需求了，但某些时候，我们仍旧有需求需要自定义一些服务端的功能，这时候就需要改造Next.js自带的服务端功能了。

官方文档在：Custom Server。koa的例子可以在官方范例代码库中进行查看：Custom Koa Server example。此外，还有一篇博客讲得不错：NextJs + KoaJs Create custom NextJs server with KoaJs。以及，另一个例子可以参考：fridays/next-routes#on-the-server。

不过官方的文档给出的信息其实也相当有限，没有任何对于next命令的细致解释，如果想要知道官方启动命令实际上做了什么，就只能去阅读源码了。简单看了下，除了启动服务器之外，next命令还是做了不少事情的，如果想要在保证这些功能的情况下兼容koa的话，是相当困难的。

这里更建议的做法是启一个纯粹的koa后端作为API的服务器，而将基本的前端页面和pages交给Next.js来进行服务。这样就可以绕开必须改动或者无法使用next命令的情况。

8. 问题及解决

8.1 TypeORM

初始Versions

next: 9.4.4
typeorm: 0.0.25

在添加一系列typeorm相关代码之后，next.js的编译会遇到报错（无法正常build）：

Syntax error: Support for the experimental syntax 'decorators-legacy' isn't currently enabled

解决方法见：Syntax error - Support for the experimental syntax ‘decorators-legacy’ isn’t currently enabled，需要在项目根目录添加文件.babelrc，并添加内容（关于babel的客制化，官方文档见：Customizing Babel Config）：

{
  "plugins": [
    [
      "@babel/plugin-proposal-decorators",
      {
        "legacy": true
      }
    ]
  ],
  "presets": [
    "next/babel"
  ]
}

当然还需要安装扩展：yarn add @babel/plugin-proposal-decorators -D。

接下来会遇到第二个报错：

error - ./node_modules/typeorm/browser/driver/DriverFactory.js
Attempted import error: 'AuroraDataApiPostgresDriver' is not exported from './postgres/PostgresDriver'.

解决方法见：Typeorm/browser cannot be compiled since version 0.2.25 #6110，解决方案简单粗暴，将typeorm的版本降到0.2.24即可。

然后会遇到第三个报错：

warn  - ./node_modules/typeorm/browser/driver/react-native/ReactNativeDriver.js
Module not found: Can't resolve 'react-native-sqlite-storage' in './node_modules/typeorm/browser/driver/react-native'

解决方法见：browser: Can’t resolve ‘react-native-sqlite-storage’ #2158。创建一个假的stub package即可。

然后就可以在_app.tsx:MyApp.getInitialProps进行数据库连接的初始化。

try {
  getConnection();
} catch (err) {
  if (err instanceof ConnectionNotFoundError) {
    await createConnection(Database.getConnectionOptions());
  } else {
    throw err;
  }
}

到实际使用的时候最后仍旧会有问题（参见：Use TypeORM with Next.js #12254）：

RepositoryNotFoundError: No repository for "..." was found. Looks like this entity is not registered in current "default" connection?
...

简单来说就是和数据库的连接正常建立了，但本地的entities文件找不到。我尝试过很多方法来解决这个问题，但最终都不能很好解决。猜想可能是next会创建build文件，而build文件中找不到entities（虽然我也尝试过给予entities绝对路径，但最后也不行）。最后还是放弃了在SSR中使用typeorm，所有的next.js中的数据访问全部都通过API来访问后端的koa服务器来解决，不再进行服务器代码直接处理。

这样当然会有不小的性能损耗，其实绕开typeorm直接在服务器自己建立连接来访问数据库也是可行的，不过小项目就算了，代码量多了维护起来比较麻烦。

资料

youtube-dl 及 ffmpeg 相关

Mon, 18 May 2020 06:02:22 GMT

1. youtube-dl 403
2. 手动下载及视频剪辑相关

1. youtube-dl 403

在使用youtube-dl进行下载的时候，时不时会遇到403报错，导致无法正常进行下载。搜了下，github上关于403报错的issue还真不少，有效的解决方案全部是要求使用extension从浏览器中导出cookie信息到文件，然后使用--cookies导入，就能正常使用了。但实际上操作下来，仍旧会报错。

其实只需要一个简单命令就能解决了：

$ youtube-dl --rm-cache-dir

2. 手动下载及视频剪辑相关

有的时候因为某些原因，使用软件下载不是很好处理，就需要手动操作，一般来说可用的下载网站随便google下就能找到，这里列几个：

下载下来的某些源是没有音频的，就需要手动处理下：

# 抽取withsound.mp4中的音频到audio.aac文件
$ ffmpeg -i withsound.mp4 -vn -acodec copy audio.aac
# 不改变任何内容，直接结合视频/音频封装为MKV/MP4
$ ffmpeg -i videoplayback.webm -i audio.aac -c:v copy -c:a copy -strict experimental output.mkv
$ ffmpeg -i videoplayback.mp4 -i audio.aac -c:v copy -c:a copy -strict experimental output.mp4

Golang Concurrency

Sun, 03 May 2020 05:02:22 GMT

1. 前言
2. 资料
3. 额外的几点

1. 前言

Go语言的并发支持在语言上是第一级原生直接支持的，就像异步事件在Node.js上是语言原生支持的一样。Go语言的并发与其他语言的多线程使用还有点不太一样，在使用的时候需要从思路上理解这个”原生支持”的概念，才能用好。因此这篇博文就对其中的一些内容做个整理，此外在golang-practice这个代码库中进行实践操作，并进行监控观察效果。

2. 资料

因着Go语言在国内的火热，大量分析和资料其实都有了，这里我尽量多做整理，不做重复发明轮子的无用功：

channel & goroutine

Golang并发模型：轻松入门流水线模型
- channel的基本运用
Golang并发模型：轻松入门流水线FAN模式
- channel的多routine协同工作
Golang并发模型：轻松入门select
- select的使用，routine的情况判断
Golang并发模型：select进阶
- select的高级运用，需要排除的select的分支处理，select的阻塞运用等
Golang并发模型：并发协程的优雅退出
- routine的退出方法
Golang并发模型：轻松入门协程池
- 和FAN模式有异曲同工之妙
Golang并发：再也不愁选channel还是选锁
- channel和锁的选择问题，根据情况有不同的选择
Golang并发模型：一招教你无阻塞读写通道
- 巧用select，在阻塞的情况下进入到不同的分支做到零等待
总结了才知道，原来channel有这么多用法！
- 总结了所有的channel用法和细节

sync & lock

Golang并发的次优选择：sync包
- sync包及锁的基本运用

3. 额外的几点

上面的资料可能因为时间问题，没有提到Context，实际上在真实场景中，对多routine的退出协作使用的更多的是context：Go Concurrency Patterns: Context。

channel和锁之间的选择简单来说就是：

如果有共享内存需要在多个routine之间共用，选择锁
如果所有的内存都无需在routine之间共享，选择channel

grpc_tools_node_protoc_ts 对 @grpc/grpc-js 的支持

Thu, 23 Apr 2020 12:02:22 GMT

1. @grpc/grpc-js

1. @grpc/grpc-js

最近grpc_tools_node_protoc_ts收到一个issue，问我可不可以支持@grpc/grpc-js。

这个库倒是不陌生，前几年就已经有了，只不过一直都没有过1.0的正式版本，一直在开发阶段。最近看了下，已经到1.0.1版本了，基本上功能完备。和提issue的人讨论了下，主要诉求是使用这个纯js实现的库做到更小的docker镜像，以及在electron这种容器中使用的时候更容易构建。应该说理由还是相当充分的，于是就花了1天多点的时间做了下migration。

因为版本做完之后用英文已经写过一遍文档了，这里就不啰嗦了，直接看英语文档即可：@grpc/grpc-js support。

grpc-tools@1.8.1 安装问题

Wed, 22 Apr 2020 01:52:22 GMT

1. 问题
2. 解决

1. 问题

安装最新版本grpc-tools@1.8.1的时候遇到了不少问题，这里做下记录。

环境：

# OS
# MacOS@10.14.6
$ node --version
# v10.15.2
$ npm --version
# 6.14.4

安装1.8.1版本的时候，直接使用npm进行会报错：

$ npm install grpc-tools@1.8.1 -g

npm install grpc-tools@1.8.1 -g
/usr/local/bin/grpc_tools_node_protoc -> /usr/local/lib/node_modules/grpc-tools/bin/protoc.js
/usr/local/bin/grpc_tools_node_protoc_plugin -> /usr/local/lib/node_modules/grpc-tools/bin/protoc_plugin.js

> grpc-tools@1.8.1 install /usr/local/lib/node_modules/grpc-tools
> node-pre-gyp install

node-pre-gyp WARN Using needle for node-pre-gyp https download
node-pre-gyp ERR! install error
node-pre-gyp ERR! stack Error: 503 status code downloading tarball https://node-precompiled-binaries.grpc.io/grpc-tools/v1.8.1/darwin-x64.tar.gz
node-pre-gyp ERR! stack     at PassThrough.<anonymous> (/usr/local/lib/node_modules/grpc-tools/node_modules/node-pre-gyp/lib/install.js:149:27)
node-pre-gyp ERR! stack     at PassThrough.emit (events.js:194:15)
node-pre-gyp ERR! stack     at ClientRequest.<anonymous> (/usr/local/lib/node_modules/grpc-tools/node_modules/needle/lib/needle.js:482:9)
node-pre-gyp ERR! stack     at Object.onceWrapper (events.js:277:13)
node-pre-gyp ERR! stack     at ClientRequest.emit (events.js:189:13)
node-pre-gyp ERR! stack     at HTTPParser.parserOnIncomingClient [as onIncoming] (_http_client.js:556:21)
node-pre-gyp ERR! stack     at HTTPParser.parserOnHeadersComplete (_http_common.js:109:17)
node-pre-gyp ERR! stack     at Socket.socketOnData (_http_client.js:442:20)
node-pre-gyp ERR! stack     at Socket.emit (events.js:189:13)
node-pre-gyp ERR! stack     at addChunk (_stream_readable.js:284:12)
node-pre-gyp ERR! System Darwin 18.7.0
node-pre-gyp ERR! command "/usr/local/bin/node" "/usr/local/lib/node_modules/grpc-tools/node_modules/.bin/node-pre-gyp" "install"
node-pre-gyp ERR! cwd /usr/local/lib/node_modules/grpc-tools
node-pre-gyp ERR! node -v v10.15.2
node-pre-gyp ERR! node-pre-gyp -v v0.12.0
node-pre-gyp ERR! not ok
503 status code downloading tarball https://node-precompiled-binaries.grpc.io/grpc-tools/v1.8.1/darwin-x64.tar.gz
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! grpc-tools@1.8.1 install: `node-pre-gyp install`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the grpc-tools@1.8.1 install script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/Jonathan/.npm/_logs/2020-04-22T01_31_02_124Z-debug.log

2. 解决

多番尝试之后，直接下载https://github.com/grpc/grpc-node代码到本地，然后将解压文件中的packages/grpc-tools拷贝到/usr/local/lib/node_modules文件夹下。

这样就能使用npm命令检查到这个包了（虽然仍有部分报错信息）：

$ npm list -g --depth=0 | grep grpc-tools
# ├── grpc-tools@1.8.1
# npm ERR! missing: node-pre-gyp@^0.12.0, required by grpc-tools@1.8.1

但实际使用的时候仍旧会有问题：

Error: spawn /usr/local/lib/node_modules/grpc-tools/bin/protoc ENOENT

意思是说找不到包下的bin文件夹下的protoc文件，之前bin文件的链接是这么做的：

/usr/local/bin/grpc_tools_node_protoc -> /usr/local/lib/node_modules/grpc-tools/bin/protoc.js
/usr/local/bin/grpc_tools_node_protoc_plugin -> /usr/local/lib/node_modules/grpc-tools/bin/protoc_plugin.js

包的bin文件夹下面也确实有这两个js文件，但确实没有不带js后缀的bin文件。

然后下载了之前安装错误时候提到的那个tar包：https://node-precompiled-binaries.grpc.io/grpc-tools/v1.8.1/darwin-x64.tar.gz，解压之后发现里面就只有一个bin文件夹，而文件夹内就正好有两个不带js后缀的bin文件，将这两个解压出来的文件放到/usr/local/lib/node_modules/grpc-tools/bin下。后续就能正常使用了。

至于为什么会503报错，以及为什么bin文件夹下有两套文件，这个就暂时先不去考虑了。

日语自学笔记

Wed, 11 Mar 2020 14:22:22 GMT

1. 学习经验
2. 学习资源
3. 基础
- 3.1 五十音
- 3.2 基本发音
4. 动词
5. 形容词
6. 形容动词
7. 动词的体、时、态
- 7.1 理解动词的体、时、态
- 7.2 体时态详解
8. 疑难 / 总结
X. 速查表
XI. 常用表达
XII. 语法解析范例

1. 学习经验

自己算了下，总共大概花了3个月左右时间学语法，纯语法，不包括单词之类的，算是有点心得，也做了点笔记，可以分享，故有此文。

1.1 自我介绍

日语学习这方面来说，我也算得上是一个怪人，至少是很偏门的类型，因此这里先做下介绍，也方便读者看是不是合适跟着我的套路来，不至于一下子就带到坑里去。

正式开始日语学习前的状态：

语法：駄目，生肉漫画能啃个大概意思，生肉小说基本残念
词汇：一般动画、影视剧里常见的词汇都OK，但因为没有认真学过，所以其实还是駄目
听力：尚可，生肉动画、影视剧能看个大概，意思能大致理解
书写：全然駄目，促音、长音之类都不知道，日语输入法也从来没打过，基本上写不出任何东西

80后，算是赶上了一个好年代，电视台直接有引进，小学开始接触日本动画；文字上接触日语是从MD的RPG梦幻之星4千年纪的终结开始。将近30年积累下来，到开始正式学日语之前，生肉游戏只要带语音的，都能大概啃下来，PS4上的うたわれるもの1-3，全部都是生肉，直接啃穿没问题。

19年12月裸考JLPT N2：159/180分。（不得不吐槽JLPT，这证书对于验证语言能力参考价值极低）

大致上这样。

这里怀念下当年在电视上能直接看高质量的动画：机器猫、太空堡垒、圣斗士星矢、灌篮高手、超音战士、十二生肖守护神、宇宙骑士、魔神英雄传、魔神坛斗士、罗德岛战记、宠物小精灵、中华小当家，我印象最深的就有这些。〔转载〕80后看过的引进动画片，来这里考古吧！—— 考验童年记忆的时刻到了。

1.2 核心语法点学习路线推荐

开始学日语之前，我的语感和语言积累其实都蛮不错的，但正式开始学习仍旧吃了不少苦头。回过头来我看了下市面上各种各样的教材和教程，感觉都没有在堆量的教学开始之前，把核心路线（纯核心语法）抽出来讲解。

无论是学校语法还是教育语法，无论是培训班还是大学老师，讲课一般都是：五十音，然后开始一课课讲内容，语法细节一点点铺在每一课中。这种做法有其好处，随着时间的消费，词汇、阅读能力、语感、语法都同步慢慢推进，非常均衡。只要时间（课时）够，后面自然就能融会贯通。但这套做法不适合我，我已经有了足量的准备，只是核心语法点没有入手而已。因此我最后的做法是把顾明耀的语法书整本啃完，然后自己梳理出一套核心语法点，当然这仍旧是很伤的一件事情，因为顾明耀的语法书说是教学书，不如说是论文资料，无论大小的语法细节里面都放进去了。对于我这样想要把核心路径整理出来的人来说，除了花时间从头到尾过一遍之外没有好的办法，事实上我也是这么做的。

然后，我这里就整理出了一套核心路径，其实新手也完全能按着这个路径来学：

选门派：学校语法/教育语法，选一边；可选项是：直接学校语法，或教育语法入门之后再转学校语法（反过来不行）；不推荐教育语法（标日）
发音：接下来自然是五十音，和如何发音
动词：动词是日语的绝对核心，对于动词的细分（继续、瞬间等等）甚至能影响到语法的应用，在其他语言里这简直是不可想象的
- 活用理解：什么是活用
- 活用形理解：活用的种类，以及这些种类的形对应的使用场景，对于各个形的理解非常重要，只有理解了形对应的场景，才能在表达的时候选择正确的活用形来用；活用形讲解、全活用形速查表
- 动词分类：活用根据动词的类型有几套不同的规则，在对动词进行活用之前显然需要先分辨它属于哪一类；动词分类
- 如何活用：如何对动词进行活用；如何活用讲解、全活用速查表以及全音便速查表
形容词、形容动词：都归类于体言，因此也都有活用，需要花点心思
- 形容词：形容词讲解、全活用速查表、全语法点速查表
- 形容动词：形容动词讲解、全活用速查表、全语法点速查表
动词的体时态：打个不恰当的比喻，之前的活用类似英语里的do -> doing的变化的学习，而体时态则类似于了解了变化之后再去学什么样的语义情况下要用这样的变化（类似进行时就要用ing这样的意思），因此要把动词真的用起来，体时态必不可少
- 理解动词的体、时、态：分别理解什么是体时态；以及，全体时态速查表
- 体时态详解：有点复杂度的，很难整理出一个捷径，只能一个个仔细过
- 补助动词：体时态里涉及到了大量的补助动词，而且在不同的体时态中，一些补助动词的语法点还各不相同，结果就是从单个补助动词的角度来看，语法点都散落在各处，因此这里整理了补助动词速查表
格助词：如果说动词、补助动词、体时态算是日语的大脑和四肢的话，格助词就是连接各处的关节，可想而知其重要性
- 全格助词语法点速查表：这是从各格助词的角度整理的语法点表格，一般来说看到某个格助词不理解其用法可以查这里
- 常用场景整理速查表：这是从格助词的使用场合角度整理的语法点表格，如果需要针对某个语法点进行格助词之间的横向比较可以查这里；此外，该章节的后半部分还罗列了一些核心格助词之间的异同和使用难点
其他助词：没有格助词那么重要，但也是语法中的重要组成部分，这里有整理一份比较常用见的助词语法速查表，同样有使用难点整理
到这里基本上所有的核心语法点都全了，发音有了、词汇可以自己背单词、动词+补助动词+体时态+格助词则组成了健全的大脑和四肢，一般的理解以及表达就都OK了，后面就是熟练度的问题
最后常用表达这里，整理了一些日常应用中绕不开必然会遇到/需要的知识点

1.3 娱乐与学习

也说说看片和学习之间的关系。语法这块弄完之后我也尝试过用看片的方式进行学习，效果真的拔群，但操作是这样的：

下双语字幕的片
第一遍看片所有语法点不清晰的地方和单词不认识的地方全部暂停，单词全部摘录到软件里，语法全部搞清楚
摘录的单词全部过一遍，保证能清晰读出来，搞清楚自动他动
第二遍以及后续N遍看片，跟着片子进行shadowing

可见，所谓的看片学习，里面已经完全不存在娱乐的成分了。经常是第一遍看完之后我根本已经忘记了片子里讲了什么（摘录单词和看语法打断了）。所以说娱乐和学习真的不能两全，当然如果只是培养语感的话，倒是可以的。

2. 学习资源

2.1 学校语法 / 教育语法

在开始学语法之前一定要选好门派，后面一般不会轻易更换。不过对新手来说也可以先从教育语法学起，有点基础后再换学校语法（一般不会有反过来的做法）。

学校语法

更注重语法本身的细节。优点是语法分析清晰，学成之后基础扎实，不容易犯错，遇到再难的表达也能轻易分解并分析其语法理论，且因其资历较深（历史久远）有大量配套的教材和工具等。缺点是入门学习较难，适合有基础的学生（或日语母语学生）学习。

特征：活用分为五段动词、一段动词、サ变动词、カ变动词。
经典教材：新编日语（高校日语教学广泛使用）、标准日语语法顾明耀版

教育语法

更注重学习的入门和语言的应用。优点是上手难度低，快学快用，但学成后语法基础不够扎实，部分活用混乱（遇到ます形的例子到底是サ变动词还是连用形），大量的语法细节被当做习惯用法教（别管为什么这么表达，遇到这种情况就是这么表达的），导致学员学了之后知道怎么用，但不知道为什么是这么用。且在工具书（特别是字典，字典一般都给终止形/原形/辞书形，不会给ます形/て形）使用上，相对学校语法，支持不够好。适合初学者入门学习（要深入学习后面还是得切换学校语法）。

特征：活用分为一类动词、二类动词、三类动词
经典教材：标准日本语（培训学校广泛使用）、大家的日本语（出口仁老师）

2.2 出口日语 / 大家的日本语

优点：

对新人友好，教程循序渐进
教程构思优秀，整体面向应用，非生硬的纯语法教学，跟着课程可以很快上手使用日语
youtube上有完全免费的教程视频，良心无比（推荐购买一个手机端教程应用，然后看视频即可，或者直接看视频也可以）

缺点：

使用的是教育语法，对于想深入的学生来说后续相对不利

适合：

未学习过日语的新手
想快速使用日语的学生

不适合：

已入学校语法门派的学生
想深入纯语法知识点的学生

资源：

2.3 时雨日语

优点：

学校语法
教学资源的细节非常优秀，学习之后能够掌握得很扎实
网站上学习资料丰富

缺点：

没有系统的教程
没有系统的教学视频
教学视频很少
网站上的学习资料只到N3

适合：

有一定基础想要把一些细节知识点打磨扎实的学生
语法速查

不适合：

没有基础的新手
教育语法的学生
希望获得系统教学的学生

资源：

2.4 Japanese Grammar Guide / 日语语法指南

优点：

非常容易入门
省略了大量细节，只求能够快速理解基本的日语

缺点：

深度不够
语法讲解不够

适合：

初步理解日语
学个大概的学生
学习目标是简单听、读的学生

不适合：

需要认真学习的学生

资源：

2.5 标准日语语法顾明耀版

大杀器。

优点是真的认真看完且融会贯通领会了，日语语法就没有你看不懂的地方了。缺点是与其说是教材，不如说是一本科研书，对于读者来说过于艰涩，不适合没有基础的学生。而且由于其编撰完全是按照对日语语言的分解而做的，所以不适合用来做以日语应用为目标的学生的教材（不能一边看一边实践，和大家的日本语是正相反的思路）。

资源就不放了，网上可以直接购买实体书，PDF全网也不是说下不到，但比较难找。由于阅读便利性的问题（实体书实在是不方便携带和检索），我买了书之后还是下了个PDF，然后用OCR软件做了带索引的文字版本PDF，遇到疑难点可以直接索引跳转方便阅读。

2.6 其他

日语教科书・日本語にほんごのテキストブック：一个wiki，只有最基础的语法，但整理的不错
活用 (日语)：动词活用的wiki
日文動詞變化筆記(3套公式、7個型態、音變與常用18種變化)
日文形容動詞(な形容詞)變化筆記(1套公式、5種型態與常用16種變化)
日文形容詞(い形容詞)變化筆記(1套公式、5種型態與常用16種變化)

2.7 软件

iOS JP mazec：手写输入软件，方便初学者只识汉字不知读音
iOS CN MOJi辞書: 日语实用词典：中日词典推荐这个，还可以建立个人词库，把不认的录入进去，后面还可以制作背词计划
iOS CN MOJiTest: 实用英语日语背单词：背词库推荐这个，N1、N2之类的；当然后续慢慢就会只需要上面那个了，毕竟背自己录入的单词比较有意义也更有效率
iOS JP 大辞泉：日语词典也需要备一个，中日词典有的时候并不是十分完美
iOS CN 彩云小译 - 语音网页文档图片全能翻译：类似Google翻译，效果还行，有的时候能看个大概

3. 基础

3.1 五十音

五十音

.	.	.	.	.
あア a	いイ i	うウ u	えエ e	おオ o
かカ ka	きキ ki	くク ku	けケ ke	こコ ko
さサ sa	しシ shi	すス su	せセ se	そソ so
たタ ta	ちチ chi	つツ tsu	てテ te	とト to
なナ na	にニ ni	ぬヌ nu	ねネ ne	のノ no
はハ ha	ひヒ hi	ふフ fu	へヘ he	ほホ ho
まマ ma	みミ mi	むム mu	めメ me	もモ mo
やヤ ya		ゆユ yu		よヨ yo
らラ ra	りリ ri	るル ru	れレ re	ろロ ro
わワ wa				をヲ o(wo)
.	.	.	.	.
きゃキャ kya		きゅキュ kyu		きょキョ kyo
しゃシャ sha		しゅシュ shu		しょショ sho
ちゃチャ cha		ちゅチュ chu		ちょチョ cho
にゃニャ nya		にゅニュ nyu		にょニョ nyo
ひゃヒャ hya		ひゅヒュ hyu		ひょヒョ hyo
みゃミャ mya		みゅミュ myu		みょミョ myo
りゃリョ rya		りゅリュ ryu		りょリョ ryo
.	.	.	.	.
がガ ga	ぎギ gi	ぐグ gu	げゲ ge	ごゴ go
ざザ za	じジ ji	ずズ zu	ぜゼ ze	ぞゾ zo
だダ da	ぢヂ ji(di)	づヅ zu(du)	でデ de	どド do
ばバ ba	びビ bi	ぶブ bu	べベ be	ぼボ bo
ぱパ pa	ぴピ pi	ぷプ pu	ぺペ pe	ぽポ po
.	.	.	.	.
ぎゃギャ gya		ぎゅギュ gyu		ぎょギョ gyo
じゃジャ ja		じゅジュ ju		じょジョ jo
びゃビャ bya		びゅビュ byu		びょビョ byo
ぴゃピャ pya		ぴゅピュ pyu		ぴょピョ pyo

元音

あ a　い i　う u　え e　お o
元音连读：あい愛，发音长短轻重基本相同
元音的清化：い　う，容易出现清化，下例当中，前面未清化，后面为清化

かた模型 kata 　きた北方 kita
かち胜利 kachi　きち基地 kichi
ほし星星 hoshi　ふし节 fushi
せき座位 seki 　すき喜欢 suki

辅音

清音：か　さ　た　な　は　ま　や　ら　わ　ぱ，这些行
浊音：が　ざ　だ　ば，这些行
拗音：きゃ　きゅ　きょ，等类似的
拨音：ん
促音：おと声音 -＞おっと otto 丈夫
长音：とり鸟 -＞とおり大街

なぁ之类的打字方法：naxa

外来语专用音节

.	.	.	.	.	.
ツァ　tsa	ファ　fa
ウィ　wi uli	ティ　thi	フィ　fi	ディ　dhi
トゥ　twu tolu	ドゥ　dwu dolu	デュ　delyu
ウェ　we ule	シェ　she sle	チェ　che	ツェ　tse	フェ　fe	ジェ　je
ウィ　wi
ウォ　ulo	ツォ　tso	フォ　fo

英文字母

| - | -

汉字

音読おんどく：汉语发音日化
訓読くんどく：日语发音与汉字含义相结合

3.2 基本发音

发音这块时雨有一篇讲得很清楚：認識「重音」日文發音。自学这块容易搞错，所以需要针对性搞清楚。

单词查询：

weblio.jp：有数字注音无发音
OJAD：有划线注音和发音，且有长句和篇章的整体发音注解功能

4. 动词

4.1 活用

讲到动词肯定就要提到动词的活用，所谓的活用，可以简单理解为因应使用的场景不同，动词本身发生的形变。这里贴下活用WIKI的描述：

4.2 活用形

用言在活用后所产生的各种不同型态就被称作活用形。这里的理解很重要，因为学习语言的最终目的是为了使用，而活用形则是最贴近使用场景的一种概念。下面分几种活用形，进行举例描述。

4.2.1 未然形

主要用来接续表示否定的助动词“-ない”，被动、可能助动词“-れる‧られる”，使役助动词“せる‧させる”，意志、推量助动词“う”等等。

场景：否定（ない）、使役（させる、せる）、被动（られる、れる）、可能（られる、れる）、尊敬（られる、れる）、意志和推测（う、よう、まい）。

否定

后接助动词“ない“、“ぬ“。

雨が降らない。/ 不下雨。
親からの手紙がなかなか来ない。/ 家里的信怎么等也不来。
一ヶ月もせぬうちに治った。/ 还没到一个月就治好了。

使役

后接助动词“させる (せる）”。

弟を買い物に行かせた。/ 让弟弟去买东西。
母は妹を買い物に行かせる。／母亲让妹妹去买东西。

被动

后接助动词“られる (れる）”。

雨に降られた。/ 被雨淋了。
彼は父に叱られた。／他受到了父亲的训斥。

可能

后接助动词“られる (れる）”。

五年後には家が建てられる。/ 五年后,房子可以建造起来。
それは食べられる。／那个能吃。

尊敬

后接助动词“られる (れる）”。

先生が帰られた。／老师回來了。

意志和推测

后接助动词“う(よう)“。

テレピの音を小さくしよう。/ 把电视的声音关小点吧。
粘土で人形を作ろう。/ 用粘土捏个娃娃吧
これには論理上の欠陥はほとんどないと言えよう。/ 大概可以说这里面几乎没有逻辑方面的问题。

一段动词和サ变动词则需要后接助动词“まい”。

あんなばかなことは二度としまい。/ 那种使事,绝不再做了
君にはこの役はとてもやれまい。/ 对你来说,这个角色大概干不了

4.2.2 连用形

用来接续其他用言，以及表示过去・完了的助动词“た”等。也有不接续其他词语，而直接拿来作为名词的用法，例如“休み”（由动词休む的连用形而来，作为名词“休息”）。

场景：构词用法、中顿、后接助动词（ます、た、たい、そうだ）、后接助词（に；て、ながら、つつ、ても、たって、ては；たり；は、も、でも、さえ；な）。

构词用法

可充当名词或与其他词素构成复合词。

直接转成名词：動きが激しい、行きはよいよい、帰りはこわい
合成词的上位词构成名词：使い道、泣き虫、出ロ
合成词的上位词构成动词：流れ込む、取り入れる、ふりかける
合成词的上位词构成形容词：蒸し暑い、聞き辛い、焦げ臭い
合成词的下位词构成名词：魔法使い、湯吞み、月見、高飛び、早起き

中顿

表示并列，有时隐含有顺接（因果等）、逆接（转折等）等语法意义。

流れは山を下り、谷を走り、野をよこぎる。/河流冲下山岗,流过山谷，穿过田野。
兄は町へ行き、僕は留守番をする。/哥哥去上街，我看家。

后接助动词

与助动词一起，构成种种语法意义。

ます

后接助动词“ます”，构成敬体。

僕は君の幸せを望みます。/我希望你幸福。
ご自由にご利用くださいませ。/请随便使用。

た

后接助动词“た”，表示过去、完了、状态以及某些特殊意义。

真ーはアジア大会で新記録を立てた。/真一在亚运会上创造了新纪录。
読んだ本をすぐに返してください。读完了的书请立即还回。
やっぱり、かぎはここにあった。/钥匙到底还是在这儿。

たい、たがる

后接助动词“たい”、“たがる”，表示愿望。

今度は立派な論文を書きたい。/下次想要写出一篇出色的论文。
彼は彼女と結婚したがっている。/他想和她结婚。

そうだ

后接助动词“そうだ“，表示即将发生某动作或有可能性。

不景気で会社がつぶれそうだ。/由于不景气,公司即将倒闭。
簡単にできそうな仕事だが、なかなか終わらない。/看似很简单的工作，却怎么也做不完。

连用+そうだ：与说话者密切相关，说话者参与。

后接助词

动词连用形后还可以接助词，增添某些特殊的意义，实现语法功能。

格助词に

后接格助词“に”，表示来去等移动动词的目的。

朝早く鮭を釣りに行った。/ー大早就出去钓鮭鱼了。
いい仕事をさがしに東京へ戻った。/回到东京寻求好工作

接续助词

后接接续助词“て”、“ながら”、“つつ“、“ても”、“たって“、“ては”等。

春が来て、雪が溶けた。/春天来了,冰雪融化了。
友と語りつつ酒を飲む。/与朋友边聊天边饮酒。

并列助词たり

后接并列助词“たり“，表示并列或举例。

ー日中踊ったり、歌ったりした。/一整天又跳舞又唱歌。

提示助词

后接提示助词“は”、“も“、“でも“、“さえ”等，再后接形式动词“する”，表示对比、强调、例示等含义。

御恩は決して忘れはしない。/决不忘您的思德
駅の案内を人々はほとんど聞きも、見もしません。/对于车站内的介绍，人们几乎听也不听，看也不看。

语气助词な

后接语气助词“な”，表示命令或要求。

危ないから、気をつけな。/危险，留神！

4.5.3 终止形

不接续其他助词，或著接续终助词而置于句末的型态。也是用言尚未活用前的基本型态。（基本形也称辞书形或字典形）

场景：结句、后接助动词（そうだ、らしい、だろう、でしょう；まい限五段サ变）、后接助词（か；な、ね、よ、なぁ、さ；が、けれども、と、から）

位于句末，用以结句

この花はいい匂いがする。/这花发出香味。
難しい言い回しをやさしく直す。/把难懂的话改得易懂些

后接助动词，助动词为其增添某种语法意义

そうだ、らしい及だろう (でしょう）
- 彼は留学の許可を得るため両親を説得するそうだ。/据说他为了获得留学的许可要去说服他的父母。
- 新人を入れてチームの若返しを図るらしい。/好像是吸收新成员,以求队伍的年轻化。
まい
- 和未然形一样，后接助动词“まい”，表示否定的意志与否定的推测两种意义。只限于五段动词和サ变动词。
- わざわざ嵐の中で登山をするものはあるまい。/恐怕没有人特地在暴风雨中登山吧。

终止+そうだ：说话者听说的事情，与说话者完全不相关。

后接助词

并列助词か
- 行くか行かないか迷っている。/不知该去不该去。
语气助词
- 后接语气助词“か”、“な”、“ね“、“よ”、“なぁ”、“さ”等，表示各种语气。
- 転んだくらいで泣く奴があるか。/有你这样摔了一下就哭的人吗?
- 急ぐから、僕はもう帰るよ。/我有急事,这就回去。
接续助词が、けれども、と、から
- 私は車の連転ができるが、兄はできない。/我会开车,可我哥不会。
- 会社は今危機にあるけれども、つぶれないと思う。/我认为公司虽然处于危机当中，但不会破产。

4.5.4 连体形

用来接续其他的体言。几乎与终止形相同，除了形容动词（な形容词）。

场景：后接体言、后接助动词（ようだ、みたいだ）、后接接续助词（ので、のに；だけ、くらい、ほど、ばかり；しか；の；こと、もの、はず、わけ、ため）。

后接体言，构成该体言的定语

流れる水と噴き上げる水。/流満的水和喷涌的水。

后接助动词ようだ、みたいだ

彼も最近新しい機械を工夫しているみたいだ。/他似乎最近也在琢磨新的机器

后接接续助词

接续助词ので、のに
- 日本語だけで十分に表せるのに、なぜ外国語を取り入れなければならないのでしょう。/只要用日语就足以表达了,可为什么非要吸收外语呢。
副助词だけ、くらい、ほど、ばかり
- 人生には、遭難するぐらい惨めなことはない。/人生中没有比遇难更悲惨的
- 眺めるだけなら、お金は要らない。/如果只是看,那么不要钱。
提示助词しか
- 后接提示助词“しか”，再后接否定意义的词语，表示除此之外别无他法
- ここまで来たら、やるしかありません。/到了这一步也只有干了。
后接语气助词の
- くずぐずしないで、さっさとするの。/别磨贈，快点做!
后接形式名词
- 后接“こと”、“もの“、“の”、“はず“、“わけ“、“ため”等，将动词名词化，增添意义，或接续由形式名词构成的惯用型。
- ここまで来て登山を中止するわけにはいかない。/已经到了这儿了,不可能停止登山。
- たいていのことは日本語で十分表せるはずだ。/大多数事情应该是能用日语表达的。

4.5.5 假定形

接续在现代日文中表示可能‧条件、古典日文中表示原因‧理由的助词“-ば”。而在文言文中的假定表现要使用未然形来接续“-ば”。

障子は破ろうと思えばすぐ破れる。/要想让拉门破,马上就能破。
ちりも積もれば山となる。/积砂成塔。

4.5.6 命令形

位于句末，表示命令。

手をあげろ!/举起手!
僕の話を聞け！/听我的话！

4.3 动词分类

理解了活用形之后，就知道在想要表达某种意思（或某种句式）的时候应该使用哪种活用形。比如说在表述否定的时候，应该使用未然形。接下来就需要知道未然形应该怎么做形变，这时候，就有好几种情况。

并不是所有的动词都按一个规则进行未然形形变，根据不同的情况，形变的方式各不相同，而这里提到的不同情况是有范式的，这个范式，可以归结为动词的分类。

动词可以分为：

五段动词
一段动词
サ变动词
カ变动词

接下来介绍如何将一个动词进行分类。知乎上有一篇很不错的方法：链接。

不是「る」结尾的动词都是五段动词
- 編む／選ぶ／歌う／抱く
是「る」结尾的动词，分以下情形
- 如果是「～する」，即サ变动词
  - する／参加する／散歩する／説明する
- 如果是「来る（くる）」，即カ变动词
  - 来る
- 如果倒数第二个假名落在「い」段或者「え」段的，即一段动词
  - 「い」段的，称为上一段
  - 「え」段的，称为下一段
  - 覚える／抱える／生きる／離れる
- 其他的仍然是五段动词
  - 破る／掘る／去る／撮る

当然了还有我们不断在强调的特殊的26个五段动词，它们貌似一段动词符合一段动词的定义，但实为五段动词。这些都需要个别记忆。

| - | - | - | -

:--- | :--- | :--- | :--- | :--- 嘲（あざけ）る | 焦（あせ）る | 要（い）る | 煎（い）る | 返（かえ）る帰（かえ）る | 限（かぎ）る | 切（き）る | 覆（くつがえ）る | 蹴（け）る遮（さえぎ）る | 茂（しげ）る | 湿（しめ）る | 知（し）る | 滑（すべ）る散（ち）る | 照（て）る | 握（にぎ）る | 练（ね）る | 骂（ののし）る入（はい）る | 走（はし）る | 减（へ）る | 参（まい）る | 混（ま）じる涨（みなぎ）る |

【补充】有的教材将动词按照词形变化规律分为1类动词、2类动词以及3类动词，其实质与五段动词、一段动词、サ变动词以及カ变动词并没有不同。两种称呼的对应关系是：　

1类动词	→	五段动词　　
2类动词	→	一段动词　　
3类动词	→	サ变／カ变

4.4 活用的规律

了解完了活用的分类，以及活用形的应用场景，随后又学习了下动词应该如何分类。接下来就要将两者组合起来了，通过活用形以及动词分类的组合，来学习活用的形变规律。

这里有两种思路，一种是根据动词分类的方式从五段动词、一段动词等的视角，来看五段动词、一段动词的未然形是怎么变化的、连用形是怎么变化的，等。

另一种思路是，从活用形的视角，来看未然形、连用形的五段动词、一段动词是怎么变化的。

这里选择使用第一种，因为首先造句的时候，先确定的是动词，然后根据动词可以知道其分类，然后根据表述的句子能决定到底是什么活用形。所以从动词分类的视角来学习如何变化是最符合实际使用情况的。

4.4.1 五段动词

五段动词的变化虽然有规则可寻，但因其变化在あ、い、う、え、お这五段音上，所以常被认为是最复杂的类型。

五段动词在变化的时候，会保留语尾最后一个假名的子音，只变化母音。举例来说：

「く」(ku)若在「あ」(a)段上变化，就变成「か」(ka)
「く」(ku)若在「い」(i)段上变化，就变成「き」(ki)

依此类推。但如果语尾最后一个假名是没有子音的「う」，若在「あ」(a)段上变化，会加上w音，变成「わ」(wa)，至于其他段就直接变化即可。

未然形

否定时变化规律：转あ段假名推量时变化规律：转お段假名

例：

单词	原形	-	活用	解释
行く	い`く`	→	い`か`・ない	不去

| - | → | いこ・う | 想要去

泳ぐ | およぐ | → | およが・ない | 不游泳

| - | → | およご・う | 想要游泳

聞く | きく | → | きか・ない | 不听

| - | → | きこ・う | 想要听

休む | やすむ | → | やすま・ない | 不休息

| - | → | やすも・う | 想要休息

特例：唯一与上述规律有违的是“ある／有、在”。“ある”的否定形式不是“あら・ない”，而是“ない／没有、不在”。

连用形

变化规律：转い段假名

例：

单词	原形	-	活用	解释
行く	い`く`	→	い`き`・ます	去
呼ぶ	よ`ぶ`	→	よ`び`・ます	呼唤

终止形

同动词辞书形（原形）

例：

行く

连体形

动词辞书形（原形）不转换，后加ひと、こと、とき等

例：

行くこと
呼ぶこと

假定形

变化规律：转え段假名

例：

单词	原形	-	活用	解释
行く	い`く`	→	い`け`・ば	去了就…
呼ぶ	よ`ぶ`	→	よ`べ`・ば	呼唤了就…

命令形

变化规律：转え段假名

例：

单词	原形	-	活用	解释
行く	い`く`	→	い`け`	去！
やる	や`る`	→	や`れ`	做！

4.4.2 一段动词

上一段动词和下一段动词的变化最为简单，只要去掉语尾最后的「る」，再加上五段动词公式一变化时需要加的字即可。

未然形

例：

单词	原形	-	活用	解释
起きる	おきる	→	おき・ない	不起床
見る	みる	→	み・ない	不看
食べる	たべる	→	たべ・よう	吃吧
寝る	ねる	→	ね・よう	睡吧

连用形

例：

单词	原形	-	活用	解释
起きる	おきる	→	おき・ます	起床
見る	みる	→	み・ます	看
食べる	たべる	→	たべ・ましょう	吃吧
寝る	ねる	→	ね・ましょう	睡吧

终止形

同动词辞书形（原形）

例：

起きる

连体形

动词辞书形（原形）不转换，后加ひと、こと、とき等

例：

起きるとき
食べること

假定形

后加れば

例：

单词	原形	-	活用	解释
起きる	おきる	→	おき・れば	起床的话，就…
見る	みる	→	み・れば	看了的话，就…
食べる	たべる	→	たべ・れば	吃了的话，就…
寝る	ねる	→	ね・れば	睡的话，就…

命令形

后加ろ(口语)、よ(文书)

例：

单词	原形	-	活用	解释
起きる	おきる	→	おき・ろ	起来！
見る	みる	→	み・よ	看吧！

4.4.3 サ变动词

未然形

词干加“し”，然后：否定加助动词“ない”，推量加助动词“よう”

例：

单词	原形	-	活用	解释
する	する	→	し・ない	不做
勉強する	べんきょうする	→	べんきょうし・ない	不学习
する	する	→	し・よう	做吧
勉強する	べんきょうする	→	べんきょうし・よう	学习吧

连用形

词干加“し”

例：

单词	原形	-	活用	解释
する	する	→	し・ます	做
勉強する	べんきょうする	→	べんきょうし・ましょう	学习吧

终止形

同动词辞书形（原形）

例：

勉強する

连体形

动词辞书形（原形）不转换，后加ひと、こと、とき等

例：

するとき
勉強すること

假定形

词干加すれば

例：

单词	原形	-	活用	解释
する	する	→	すれば	做的话，就…
勉強する	べんきょうする	→	べんきょう・すれば	学习了的话，就…

命令形

词干加しろ(口语)、せよ(文书)

例：

单词	原形	-	活用	解释
する	する	→	しろ	快做！
勉強する	べんきょうする	→	べんきょう・しろ	快学习！

4.4.4 カ变动词

因为只有一个来る（くる）就直接上例子了

未然形

くる → こ・ない
くる → こ・よう

连用形

くる → き・ます

终止形

くる

连体形

くる

假定形

くる → くれば

命令形

くる → こい

4.4.6 音便

只有非さ(sa)行(语尾最后一个假名为す)的五段动词才会有音便，当这类的五段动词连用形后接过去式助动词た或是接续助词て、ては、たも、たん、たって时，习惯上会自然省略连用形带i母音的假名，而形成促音便、拨音便或是イ(i)音便。

促音便

发生条件及变化：

原形动词语尾最后一个假名是う、つ、る时：使う、待つ、乗る
只限连用形：う → い、つ → ち、る → り
后续为て或た
活用会被转成っ：い → っ、ち → っ、り → っ

例：

单词	原形	-	连用形	接续	活用/音便
使う	つかう	→	つかい	ます	つか`い`・ます

| - | → | つかい | て | つかっ・て

待つ | まつ | → | まち | ます | まち・ます

| - | → | まち | た | まっ・た

乗る | のる | → | のり | ます | のり・ます

| - | → | のり | て | のっ・て

拨音便

发生条件及变化：

原形动词语尾最后一个假名是ぬ、ぶ、む时：死ぬ、呼ぶ、飲む
只限连用形：ぬ → に、ぶ → び、む → み
后续为て或た
活用会被转成ん：に → ん、び → ん、み → ん
ん后面的假名会浊化：て → で、た → だ

例：

单词	原形	-	连用形	接续	活用/音便
死ぬ	しぬ	→	しに	ます	し`に`・ます

| - | → | しに | て | しん・で

呼ぶ | よぶ | → | よび | ます | よび・ます

| - | → | よび | た | よん・だ

飲む | のむ | → | のみ | ます | のみ・ます

| - | → | のみ | て | のん・で

イ音便

发生条件及变化：

原形动词语尾最后一个假名是く或ぐ时：書く、聞く
只限连用形：く → き、ぐ → ぎ
后续为て或た
活用会被转成い：き → い、ぎ → い
ぎ的情况い后面的假名会浊化：て → で、た → だ

例：

单词	原形	-	连用形	接续	活用/音便
書く	かく	→	かき	ます	か`き`・ます

| - | → | かき | て | かい・て

聞く | きく | → | きき | ます | きき・ます

| - | → | きき | た | きい・た

嗅ぐ | かぐ | → | かぎ | ます | かぎ・ます

| - | → | かぎ | て | かい・で

例外

行く（いく）在后接て、た时，不发生イ音便，而是发生促音便。

行く+て → 行って
行く+た → 行った

4.5 活用的范式

日本的动词在不同时式(现在、过去、意志邀约、无意志未来(推测过去、推测未来))、语态(常体、敬体)、语气(肯定、否定)，可有5*2*2=20种组合，但意志邀约并没有否定语气，所以只剩下18种组合，称为「动词十八式」。

时式	语气	语态	范式	范例
现在式	肯定	常体	辞书形（原形）	行く去
现在式	肯定	敬体	连用形+ます	行きます要去
现在式	否定	常体	未然形（否定）+ない	行かない不去
现在式	否定	敬体	连用形+ません	行きません不要去
过去式	肯定	常体	连用形+过去式助动词た	行った去了
过去式	肯定	敬体	连用形+ました	行きました去过了
过去式	否定	常体	未然形（否定）+なっかた（ない去い加かった）	行かなかった没有去
过去式	否定	敬体	连用形+ませんでした	行きませんでした没有去过
意志邀约	肯定	常体	未然形（意志）+う	行こう去吧！
意志邀约	肯定	敬体	连用形+ましょう	行きましょう一起去吧！
无意志未来推测未来	肯定	常体	辞书形+だろう	行くだろう要去吧！
无意志未来推测未来	肯定	敬体	辞书形+でしょう	行くでしょう要去吧！
无意志未来推测未来	否定	常体	未然形（否定）+ない+だろう	行かないだろう不去吧！
无意志未来推测未来	否定	敬体	未然形（否定）+ない+でしょう	行かないでしょう不要去吧！
无意志未来推测过去	肯定	常体	连用形+过去式助动词た+だろう	行っただろう去过了吧！
无意志未来推测过去	肯定	敬体	连用形+过去式助动词た+でしょう	行ったでしょう有去过了吧！
无意志未来推测过去	否定	常体	未然形（否定）+なかった（ない去い加かった）+だろう	行かなかっただろう没去过吧！
无意志未来推测过去	否定	敬体	未然形（否定）+なかった（ない去い加かった）+でしょう	行かなかったでしょう没有去过吧！

5. 形容词

5.1 活用

一个形容词必定由い结尾，这即是其原形（终止形）。

5.2 活用的规律

未然形

变化规律：去い + かろ + 推量助动词う / かった（过去式）

例：

京都の桜は美しかろう。
昨日はとっても楽しかった。

连用形

变化规律：去い + く +

名词/副词
て（中止接续）
ない（否定）
なる（表变化）

例：

美味しくてたまらない。
彼女は全然美しくない。
だんだん暑くなる。

终止形

原形，无变化

例：

美味しい

连体形

变化规律：无变化，原形 + ひと、こと、とき、ところ、もの或其他名词

例：

美味しいご飯

假定形

变化规律：去い + ければ + ···

例：

楽しければ···

5.3 活用的范式

日本的形容词在不同时式(现在、过去、推测过去、推测未来)、语态(常体、敬体)、语气(肯定、否定)，可有4*2*2=16种组合，称为「形容词十六式」。

以「美味しい」(おいしい)举例，变化方式如下：

时式	语气	语态	范式	范例	翻译
现在式	肯定	常体	终止形（原形）	美味しい	好吃的
现在式	肯定	敬体	终止形（原形）+です	美味しいです	美味的
现在式	否定	常体	连用形+くない	美味しくない	不好吃的
现在式	否定	敬体	连用形+くない+です连用形+く+ありません	美味しくない美味しくありません	不美味的
过去式	肯定	常体	未然形+かった	美味しかった	好吃的
过去式	肯定	敬体	未然形+かった+です	美味しかったです	美味的
过去式	否定	常体	连用形+くなかった	美味しくなかった	不好吃的
过去式	否定	敬体	连用形+くなかった+です连用形+く+ありません+でした	美味しくなっかたです美味しくありませんでした	不美味的
推测未来	肯定	常体	终止形（原形）+だろう	美味しいだろう	好吃吧
推测未来	肯定	敬体	终止形（原形）+でしょう	美味しいでしょう	美味吧
推测未来	否定	常体	连用形+くない+だろう	美味しくないだろう	不好吃吧
推测未来	否定	敬体	连用形+くない+でしょう	美味しくないでしょう	不美味吧
推测过去	肯定	常体	未然形+かった+だろう	美味しかっただろう	好吃吧
推测过去	肯定	敬体	未然形+かった+でしょう	美味しかったでしょう	美味吧
推测过去	否定	常体	连用形+くなかった+だろう	美味しくなかっただろう	不好吃吧
推测过去	否定	敬体	连用形+くなかった+でしょう	美味しくなかったでしょう	不美味吧

6. 形容动词

形容动词和形容词的差别其实不用想太多，只要把它当作是活用方式不同的形容词即可。

6.1 活用

一个形容动词必定由だ(da)结尾，这即是其原形（终止形）。

6.2 活用的规律

未然形

变化规律：原形 + ろう(推测)

例：

綺麗だろう。

连用形

变化规律：去だ +

だった(过去)
ではない(否定)
に(副词)
に成る(になる, 表变化)

例：

綺麗ではない。

终止形

原形，无变化

例：

綺麗だ。

连体形

变化规律：去だ + な + ひと、こと、とき、ところ、もの(人、事、时、地、物)或其他名词

例：

綺麗なもの。

假定形

变化规律：去だ + なら + ···

例：

綺麗なら···

6.3 活用的范式

日本的形容动词在不同时式(现在、过去、推测过去、推测未来)、语态(常体、敬体)、语气(肯定、否定)，可有4*2*2=16种组合，称为「形容动词十六式」。

以「静かだ」(しずかだ)举例，变化方式如下：

时式	语气	语态	范式	范例	翻译
现在式	肯定	常体	终止形（原形）	静かだ	安静的
现在式	肯定	敬体	终止形（原形）去だ+です	静かです	安静的
现在式	否定	常体	连用形+ではない	静かではない	不安静的
现在式	否定	敬体	连用形+では+ありません	静かではありません	不安静的
过去式	肯定	常体	连用形+だった	静かだった	安静的
过去式	肯定	敬体	终止形（原形）去だ+でした	静かでした	安静的
过去式	否定	常体	连用形+ではなかった	静かではなかった	不安静的
过去式	否定	敬体	连用形+では+ありません+でした	静かではありませんでした	不安静的
推测未来	肯定	常体	未然形（即原形+ろう）	静かだろう	安静吧
推测未来	肯定	敬体	终止形（原形）去だ+でしょう	静かでしょう	安静吧
推测未来	否定	常体	连用形+ではない+だろう	静かではないだろう	不安静吧
推测未来	否定	敬体	连用形+ではない+でしょう	静かではないでしょう	不安静吧
推测过去	肯定	常体	连用形+だった+だろう	静かだっただろう	安静吧
推测过去	肯定	敬体	连用形+だった+でしょう	静かだったでしょう	安静吧
推测过去	否定	常体	连用形+ではなっかた+だろう	静かではなっかただろう	不安静吧
推测过去	否定	敬体	连用形+ではなっかた+でしょう	静かではなっかたでしょう	不安静吧

7. 动词的体、时、态

7.1 理解动词的体、时、态

在英语的学习中，都会教：一般现在时、一般过去时、现在进行时、过去进行时、现在完成时、过去完成时等，被动态，等，这种被称为时态。在进行表达的时候，需要根据实际的意思进行时态的选用，才不会表达出错误的意思。英语在这方面是比较简单的，每一个时态都有固定的范式：现在进行时ing，被动态ed，等。

日语中也有类似的需求和语法规则，但在这方面，日语要复杂得多得多，日语分为三重概念：体、时、态，而且每个概念里都有诸多细节，并不能像英语一样简单罗列成几个范式。

日语中的体、时、态

体：动词所表现的动作、作用有的可以是一个过程，即存在着动作作用的开始、进行和结束等阶段。动词的“体（アスペクト）”就是记述动作、作用等处于何种进行情况的语法范畴。
- 持续体：持续体表示动作、行为在某一时间内持续进行或正在进行、反复进行。
- 存续体：存续体表示动作、行为所造成的状态、所形成的結果还在保留着。
- 完成体：完成体指的是动作、行为的完成、结束。
- 准备体：准备体表示该动作是为下一步做准备而做的。
- 即将体：即将体表示动作、行为、作用等就要发生。
- 起始体：起始体表示动作、行为、作用的开始。
时：时（テンス）是一个语法范畴，指通过一定的语法形式表示动作、作用、状态的发生时间与某一基准时间（通常是说话的时间）之间的关系。
- 非过去时：非过去时由动词（包括体的补助动词、构成态的助动词以及敬语助动词ます）的终止形直接构成。
- 过去时：过去时由“动词连用形+た”构成。这里说的动词，也包括补助动词及动词型活用的助动词。
- 分句中的时：参考8.5的整理。
态：基于着眼点的不同，描述同样一件事情时，既可以从动作的施事者出发，也可以从动作的受事者出发，还可以从指使者出发，如此等等。由于动词所指动作与主语的关系所形成的谓语动词的形态变化，叫作动词的“态（ヴォイス）”。
- 被动态：当描述某一动作、行为时，不是以施事者为主角，而是以承受者为主角进行描述，该动词所表现的形态，就是被动态。
- 使动态：在描述某一动作、行为时，不是以施事者为主角，而是以指使者、容许者或者促成者为主角描迷，该动词所表现的形态就是使动态。
- 可能态：当叙述焦点不在动作本身，而转移到实现动作的能力或可能性时，动作所发生的形态变化，称为可能态。
- 自然发生态：描述的焦点在于动作行为是自然而然地发生、自然而然地产生某种结果时，动词的形态变化，就是自然发生态，可简称“自发态”。

7.2 体时态详解

因为学习语言的目的是为了使用，所以将可以复合组合的体时态拆开一个个单独讲解和理解其实并没有意义，重要的是如何将表达一个个意思的一组组体时态的组合理解并学会，这样才能拿来实际运用。这也是为什么你看出口仁老师的视频教程有N5语法一览这样的视频集合，里面每一个视频每一课其实就是一个体时态组合起来的表达运用，学会了就可以直接使用；这也是为什么顾明耀的语法书学了之后你不能直接拿来用的原因，因为那本书把所有的概念都拆散了拿来详细分析，只有各部分的细节，没有组合运用。

补助动词速查

下述语法涉及到了大量补助动词，且部分补助动词有一词多用的特点，导致语法点散落在多个体时态章节中，因此将其统一整理成表格：

补助动词	语法点
ている	持续体存续体ている和てある的区别瞬间动词+た表经历、记录形容性动词瞬间动词+ている的否定形式
てくる	持续体、空间由远及近、起始体、状态变化、显现过程
ていく	持续体、空间由近及远、状态变化、消失过程
てある	存续体ている和てある的区别ておく和てある的区别
てしまう	完成态、消极态度、情不自禁、约音用法
ておく	将来打算、放任态度、约音用法ておく和てある的区别、事先准备
れる/られる	被动态可能态：能力、可能性、许可自然发生态表尊敬
せる/させる	使动态：命令、放任

7.2.1 一般时态

使用场景

表示一般现在或一般过去的动作和行为。

构成

ます

时式	语气	常体	敬体
非过去	肯定	辞书形	连用形+ます
非过去	否定	未然形+ない	连用形+ません
过去时	肯定	连用形+た	连用形+ました
过去时	否定	未然形+なっかた	连用形+ませんでした

7.2.2 进行时态（持续体）

使用场景

表示持续进行中的或反复进行的动作和行为。

构成

时式	语气	常体	敬体
非过去	肯定	`继续动词`连用形+ている连用形+てくる连用形+ていく	`继续动词`连用形+ています连用形+てきます连用形+ていきます
非过去	否定	`继续动词`连用形+ていない连用形+てこない连用形+ていかない	`继续动词`连用形+ていません连用形+てきません连用形+ていきません
过去时	肯定	`继续动词`连用形+ていた连用形+てきた连用形+ていった	`继续动词`连用形+ていました连用形+てきました连用形+ていきました
过去时	否定	`继续动词`连用形+ていなかった连用形+てこなかった连用形+ていかなかった	`继续动词`连用形+ていませんでした连用形+てきませんでした连用形+ていきませんでした

语法补充

关于时态

用多了就会发现，日语里ている等持续体的用法，和英语中的进行时还不能完全对等。日语中的持续体，更多的是表示动作的持续，可以理解为，什么时候用持续体什么时候用存续体，更多取决于执行的动词（动作）是继续动词（持续性动作）还是瞬间动词（瞬间动作），而并非取决于语义理解上的正在（进行时）和已经（完成时）。进行时只能说是持续体可能表达的其中一种情况。

举个例子：

それは我々もずっと前から懸念していました。/这件事情我们之前也一直很担心。
可以看下两种翻译的差别：之前一直很担心/之前正在担心，这里显然是前者

ている

ている其本身转て形的时候，会变成ていて，在口语中有时会转为てて，方便发音：
- 彼らを見張っていて欲しい。
- 彼らを見張ってて欲しい。

てくる

てくる除了进行时态之外，还有多种语法意义：

时间由过去向现在发展，同时动作持续进行或重复进行；这是当前章节所描述的进行时态，多用于过去时
- 三時から、雨が降ってきました。/3点开始一直都在下雨。
- この事件をずっと調べてきたのです。
空间由远及近
- 子供が走ってきました。
体时态中，体的起始体
- 雨が降ってきた。/（刚刚）开始下起雨来。
表示状态变化、显现过程
- だんだん暑くなってきました。/（从前一阵开始）慢慢变热了。

ていく

ていく除了进行时态之外，还有多种语法意义：

时间由现在向将来发展，同时动作持续进行或重复进行；这是当前章节所描述的进行时态，多用于非过去时
- これからも頑張っていきましょう。
- 二人で生きていきます。
空间由近及远
- バスがやっていきました。
表示状态变化、消失过程
- だんだん暑くなっていきます。/（最近开始）慢慢变热了。

7.2.3 行为结果、状态（存续体）/ 完成时态△

使用场景

表示动作、行为所造成的状态、所形成的結果还在保留着。同时，ている也可以表示经历、记录。

构成

ている：N5文法37【表現篇】「ている／てある」
てある：N5文法37【表現篇】「ている／てある」

时式	语气	常体	敬体
非过去	肯定	`瞬间动词`连用形+ている连用形+てある	`瞬间动词`连用形+ています连用形+てあります
非过去	否定	`瞬间动词`连用形+ていないてない	`瞬间动词`连用形+ていません连用形+てありません
过去时	肯定	`瞬间动词`连用形+ていた连用形+てあった	`瞬间动词`连用形+ていました连用形+てありました
过去时	否定	`瞬间动词`连用形+ていなかった连用形+てなかった	`瞬间动词`连用形+ていませんでした连用形+てありませんでした

语法补充

存续体是日语中很特殊的用法（其他语言的时态中，并没有这样非常针对性的构成），表示动作行为所造成的状态、结果仍旧存在着。这个语法点在理解上的主要问题是：

存续体中的重要组成部分补助动词ている在进行时态中也存在，这就导致了实际运用时的理解困难：
- 存续体：井上先生はいま中国に行っている。/井上老师现在到中国去了。（不是过去这个行为，而是已经在那边的状态）
存续体的状态、结果的含义在某些场景和句意下很容易和完成体的翻译以及准备体的ておく混淆：
- 存续体：このご飯はもう腐っている。/这米饭已经馊了。
- 存续体：教授には、もう受賞のお祝いの電報を打ってある。/已经给教授发去了获奖的祝贺电报。
- 存续体：新しいバットを注文してある。/已经定好了新球棒。
- 准备体：自転車はもう買っておいた。/自行车已经买好了。

下面详细讲解下语法点和区别：

存续体：
- ている：
  - 存续体的ている必须和瞬间动词组合使用，而进行时态的ている（持续体）则是和继续动词组合使用
  - 正因为是瞬间动词，所以虽然中文翻译都是已经...但和完成体不同，着重点在于动作结束后留下的结果和状态，而不是动作本身
    - 桜の木が枯れている。/櫻树已经枯死了。
    - このご飯はもう腐っている。/这米饭已经馊了。
- てある：
  - てある必须搭配他动词使用，强调的是人为的结果
  - 同样的，翻译虽然是已经...，但强调的是结果和状态
  - 自动词
    - 並ぶ+ている
    - お皿が並んでいる。
    - 盘子已经排好了。（强调盘子排好的状态）
  - 他动词
    - 並べる+てある
    - お皿が並べてある。
    - 盘子已经（被某人）排好了。（强调某人排好了盘子）
- ている和てある的区别：
  - ている着重于结果和状态
    - ドアが開いている。
    - 门开着。（强调状态）
  - てある着重于人为的结果
    - ドアが開けてある。
    - （我把）门（打开）开着。（人为结果）
  - 助词使用上
    - 持续体：对象+を+他动词+ている：お皿を並べている。(正在排盘子)
    - 存续体：对象+が+他动词+てある：お皿が並べてある。(某人排好盘子)
    - 存续体：对象+が+自动词+ている：お皿が並んでいる。(盘子排好着)
- ている：在作定语从句中的谓语时，可以变化为瞬间动词+た的形式：
  - メガネをかけている人は王さんだ。
  - メガネをかけた人は王さんだ。
准备体：
- ておく（准备体）和てある（存续体）在为了某事做好准备...（已经...）这个用法上的语义是一致的，但有区别
  - ておく必须搭配意志动词使用，可以表达请求、命令、愿望、劝诱等意思
  - ておく着眼点在于人为结果，行为的人；而てある则只关注结果和状态
  - ておく更多地含有事先准备的意思，因此多用过去时，而てある则无所谓时的问题，过去非过去都可
    - 自転車はもう買っておいた。/自行车已经买好了。
    - 新しいバットを注文してある。/已经定好了新球棒。

ている

此外，关于ている还有几点补充：

持续体的ている还可以表示经历、记录
- 这个用法和表示行为的结果和状态类似，但实际上意思还是有点不同的
- 这个不同更多的不是从语法上，而是从释义上来理解（也就是说不需要想太多）
  - 存续体表状态：井上先生はいま中国に行っている。/井上老师现在到中国去了。
  - 存续体表经历：井上先生は中国に何回も行っている。/井上老师去过好多次中国。
形容性动词
- 形容性动词+ている可以表示动作的性质，这种用法更类似于形容词
- 因为这种用法仍旧还是ている，所以要和继续动词的持续体分清楚
  - あの人は太っています。
  - 彼の作品は優れています。
瞬间动词+ている的否定形式
- 虽然在上面的构成表（一般规律）中有写否定形式是
  - 非过去：常体：连用形+ていない；敬体：连用形+ていません
  - 过去时：常体：连用形+ていなかった；敬体：连用形+ていませんでした
- 但实际使用的时候则是去掉ている的一般时态的否定形式
  - 构成：
    - 非过去：常体：未然形+ない；敬体：连用形+ません
    - 过去时：常体：未然形+なかった；敬体：连用形+ませんでした
  - 举个例子知る，一般对话都是：
    - 知っていますか。/你知道吗？
    - 知らない。/知りません。/我不知道。

7.2.4 完成时态（完成体）

使用场景

表示动作、行为的完成、结束。

构成

てしまう：N4文法19「てしまう」補助動詞

时式	语气	常体	敬体
非过去	肯定	连用形+てしまう	连用形+てしまいます
非过去	否定	连用形+てしまわない	连用形+てしまいません
过去时	肯定	连用形+てしまった	连用形+てしまいました
过去时	否定	连用形+てしまわなかった	连用形+てしまいませんでした

语法补充

てしまう

完成时态：与存续体的区别（更完整的细节可以查看章节7.2.3）
- 完成体てしまう着重的是行为的完成，动作做完这件事
  - 果物を全部食べてしまった。/把水果全吃完了。
  - 句子的重点在吃完这件事，而不是吃完之后的状态（空盘子、还要再去弄点等）
- 存续体ている、てある注重的是行为完成后造成的结果或状态，之前在存续体的篇幅里也说过了，存续体的句子翻译过来个个都是已经...，从这点上来看，存续体其实都是完成时态，但着重点在于结果和状态而已
  - お皿が並んでいる。/盘子已经排好了。
  - 句子的重点在排好这个状态，而不是排的动作的完成（后面可以很自然接吃饭之类的后续，因为吃饭的准备动作做完了）
完成时之外的其他用法
- 表示遗憾、惋惜、悔恨等消极态度
  - 電車の中にスマホを忘れてきてしまった。（后悔）
  - 亀が死んでしまいました。（遗憾）
- 情不自禁的行为
  - 笑い事ではないのに笑ってしまった。
  - 思わず泣いてしまった。
てしまう可以约音成ちゃう或ちまう的形式
- あなたを待っている間に手紙を書いちゃった。/等你的时候,写完了信。
- きれいに財産を使っちゃう。/把财产花个一干二净。

7.2.5 完成准备（准备体）/ 完成时态△ / 将来打算

使用场景

表示后续动作的准备工作的完成（过去时），或表示将来的打算（非过去时）。

构成

ておく：N4文法20「ておく」補助動詞

时式	语气	常体	敬体
非过去	肯定	连用形+ておく	连用形+ておきます
非过去	否定	连用形+ておかない	连用形+ておきません
过去时	肯定	连用形+ておいた	连用形+ておきました
过去时	否定	连用形+て置かなかった	连用形+ておきませんでした

语法补充

ておく

关于ておく与てある的区别，以及完成时态的更完整的细节可以查看章节7.2.3。

补充语法点：

时的问题：
- 虽然在章节7.2.3的时候说了，ておく有很多情况是使用过去时，这种情况一般是表示已经完成的准备
  - 自転車はもう買っておいた。/自行车已经买好了。
- 但也有很多情况是使用非过去时，这种情况一般是表示将来的打算
  - 旅行の前に、切符を買っておく。（尚未去买车票，准备去买）
  - 試験までに、単語を覚えておきます。（尚未开始准备考试，接下去准备背单词）
表示放任：
- 这种使用情况下，ておく表示的不是准备工作或将来打算，而是完成之后的放任态度，这里的时也是过去时非过去时皆可
  - 看板をいつまでも出しておく。/让招牌一直放在外面。
  - とりあえず押し入れに入れておけ。/先放到壁橱里再说。
  - もうすぐアニメの時間だから、テレビをつけておいてよ。/马上就要播动画了，电视就让它开着吧。
ておく可以约音成とく
- 言っとくよ。

7.2.6 被动态

使用场景

表示动作行为的主语并非实施者，主语为承受者的情况。

构成

分类	构成	范例	变化
五段动词	未然形+れる	言う	言われる
一段动词	未然形+られる	食べる	食べられる
サ变动词	词根+される(约音)	勉強する	勉強される
カ变动词	未然形+られる	来る	来(こ)られる

Aが/はBに/から/によって...CをD（ら）れる。
- 太郎が犬にかまれた。/太郎被狗咬了。
- 太郎は先生からよくほめられる。/太郎常受到老师表扬。
- 次郎が太郎に英語を教えられる。/次郎由太郎教(他)英语
A：动作承受方，主语
B：动作实施方，人物宾语
C：传递物，事物宾语
D：动作
C的这一部分并不是必须的，有的表述需要有的则不需要；如果存在的话，则必须在A和B两者之间有物质的或精神的东西传递（即C）

语法补充

直接被动句：
- 直接被动句的动词都是他动词
- 直接被动句可以还原为主动句进行叙述
- 直接被动句就是最常见的被动句表述方式
  - 李さんが王さんから辞書を渡された。/小李从小王手里接过递过来的辞典。
间接被动句：
- 间接被动句的动词可以是自动词或他动词
- 自动词的间接被动句一般无法直接还原成主动句
- 他动词的间接被动句可以还原为主动句
- 间接被动句中，动词（无论是自动词还是他动词）并没有直接作用于叙述的焦点，而是句中的主语从动作施事者那里遭受到不利的影响
  - 叙述的焦点与动作的施事者或承受者有必然的联系
    - 混んだ電車の中で足を踏まれた。/在拥挤的电车里被人把脚踩了。
    - 幼い時に、父に死なれた。/很小的时候父亲就死了。
  - 二者没有必然联系，而是在叙述客观事实时偶然建立起了关系
    - 私は帰る途中、雨に降られた。/我回来的路上被雨淋了。

7.2.7 使动态：命令、放任

使用场景

表示动作行为的主角并非行为的实际实施者，而是行为的要求者、指使者的情况。

构成

分类	构成	范例	变化
五段动词	未然形+せる	書く	書かせる
一段动词	未然形+させる	食べる	食べさせる
サ变动词	词根+させる(约音)	勉強する	勉強させる
カ变动词	未然形+させる	来る	来(こ)させる

Aが/はBに/をCをD（さ）せる。
- 先生が彼に論文を書かせる。/老师让他写论文了
- 先生が太郎を廊下に立たせる。/老师叫太郎站在走廊里。
A：动作指使者，主语
B：动作实施方，使动对象，人物宾语
C：执行对象，事物宾语
D：动作
C的这一部分并不是必须的，有的表述需要有的则不需要

这里的B应该使用に/を中的哪一个需要按情况操作，具体可以查看下面。

语法补充

格助词

他动词：
- 使动对象都用に
  - 先生が彼に論文を書かせる。/老师让他写论文了
  - 彼にかってに言わせておこう。/让他随便说吧。（放任）
- 具有他动词倾向的自动词也用に
  - 彼は人々にその提案に反対させた。/他让人们反对这项提议。
自动词：
- 强制性
  - 强制、命令等，使动对象都用を
    - 遊びたかったが、父は私たちを買いものに行かせた。/我们很想玩,可是爸爸却叫我们去买东西。
    - 子どもを9時までに寝させる。/让孩子在9点以前睡觉。
  - 表示引发某种结果、间接责任导致某种结果等，使动对象也使用を
    - 謝まるつもりだが、かえって彼女を怒らせた。/我是要向她道歉的,没想到却使她发了火。
- 非强制性
  - 放任、允许等，使动对象用に
    - 父はやっと私たちに買い物に行かせるようになった。/爸爸终于(肯)让我们去买东西了。
    - 小さい子どもに一人で大通りを渡らせるのは危ない。/让小孩子单独过马路很危险

放任、允许

使动态有一点一定要注意的是，它很多时候用在放任、允许的表述上，这其实是相当反直觉的，和命令、强制完全相反，所以一定要小心阅读：

母は子供を遊ばせています。/妈妈放任孩子玩。
母は弟をアメリカへ留学させました。/妈妈允许弟弟去美国留学。

使动态的被动态

这种表述方法有很强的强迫、被迫的意思，如果是精神性的词汇，则表示非自发而是由其他东西触发的状态
- 先生が太郎を廊下に立たせた。/老师叫太郎站在走廊上。（使动主动）
- 太郎が先生に廊下に立たせられた。/太郎披老师要求站在走廊上。（使动被动）
- 就職活動で自分自身について真剣に深く考えさせられた。/由于找工作，迫使我对自己进行了认真深入的思考。（精神性）
被使动态的约音
- 五段动词被使动态常常发生如下的约音现象：
  - 書く (せる)→ 書かせる (られる)→ 書かせられる (约音)→ 書かされる
  - 歌う (せる)→ 歌わせる (られる)→ 歌わせられる (约音)→ 歌わされる

7.2.8 可能态：能力、可能性、许可

使用场景

表示动作行为的能力或可能性。

构成

基本构成和被动态7.2.6一致。

此外，五段动词可以转え段之后+る，转为下一段动词，来表示可能态：

五段动词	れる	可能态
買う	買われる	買える
書く	書かれる	書ける
行く	行かれる	行ける
読む	読まれる	読める

实际上五段动词的可能态用的更多的是这种构成，也方便和被动态区别开来。

Aが/はBがC（さ）れる。
- あの子は自分で来られます。/那孩子自己能过来。
- （私は）ピアノが弾けるようになった。/（我）能弹钢琴了。
A：动作实施者，主语
B：执行对象/可能性，事物宾语
C：动作
B的这一部分并不是必须的，有的表述需要有的则不需要
B的格助词是が，发生了格转换

语法补充

语义

和其他一些用法一样，可能态也能表示多种语义：

表示能力
- この魚は飛ぶことができる。/这种鱼会飞。
- ピアノが弾けるようになった。/能弹钢琴了。
表示可能性
- 用事があって出席できません。/有事不能出席。
表示许可
- 授業中は、大声で話すことができない。/上课时不许太声说话。

7.2.9 自然发生态

使用场景

表示动作行为是自然而然地发生、自然而然地产生某种结果。

构成

基本构成和被动态7.2.6一致。

且也有和可能态7.2.8一样的五段动词下一段构成法。

Aが（さ）れる。
- 雪が降ると、故郷のことが思い出される。/ー下雪就不由得想起故乡。（执行对象存在，使用格助词が）
- あの映画を見ると泣けてしかたがない。/看那部电影让人哭泣不已。（五段动词的下一段转换）
A：执行对象，不是必须的，可能存在也可能不存在
A的格助词是が

语法补充

意义

表示不由自主地产生某种行为或结果，与人为动作不同。着重点在于行为发生顺乎自然，不关注行为的执行者本身。

れる/られる的额外用法：表尊敬

对话题中的人物动作添加敬意。

先生の考えられたとうりです。/正如老师您所想的那样。
課長はいつ富士山に登られたのですか。/科长您是什么时候去登的富士山？

8. 疑难 / 总结

8.1 发音：单词的促音/长音

单词中的促音和长音估计是最让人头痛的了。说实在的，基本上没什么很好的办法能解决。唯一的办法就是提升熟练度，也就是反复练习。一般最容易搞错促音和长音的时候是初见，经常不容易从听音中发现音节的延长，但只要是真的学习和背诵过的单词，一般不太会错。

促音就是将前面的发音中断一瞬之后，继续后面的发音；长音则是将前面的发音延长一瞬。说起来是一瞬，但实际发音的时候还是很明显的，多练就很清楚。

举个比较恶心的例子：

実習じっしゅう０
自習じしゅう０
自主じしゅ０

8.2 发音：清音浊音区分

時雨日文【關於清音聽成濁音這件事】頑張って？頑張っで？【PTK法則？】
為什麼「頑張って」聽起來像「頑張っで」？PTK

规则：

单词之中如果出现「P、T、K」的日文，通常听起来就会接近「B、D、G」。

举例：

頑張ってね（gan ba tte ne）→ T
- 听起来有点接近「頑張っでね」→ D
待ってください（ma tte ku da sai）→ T
- 听起来有点接近「待っでください」→ D
いっぱい飲んでね（i ppa i non de ne）→ P
- 听起来有点接近「いっばいのんでね」→ D
そっか（so kka）→ K
- 听起来有点接近「そっが」→ G

但事实上，这仅只是可能的问题，一个单词里听上去像浊音的发音实际上真的有可能是浊音，如：袖そで。说到底其实没有什么好的区分方法，还是只能靠自己熟悉，多读多背。

8.3 动词：自动词他动词区分

時雨日文【自動詞、他動詞的用法】自他同形？純自動詞？純他動詞？

看到一个动词，要区分其是自动词还是他动词没有完美的规律可循，虽然有一定规律可以借鉴。所以真正的区分方法还是和之前的促音长音一样，要靠练习，增加熟练度。

自动词：

自然现象或自发的事项，一般没有动作执行者；有些情况下，虽然存在着动作执行者，但事情的发生并不以其意志为转移，或者执行者不是叙述焦点
財布が落ちる。/钱包掉落视角在掉落这件事情上
温度が上がる。/温度上升

他动词：

他动词常常涉及动作执行者，虽然在使用时动作执行者未必都出现，但是动作执行者是隐含在动词的词义之中的
財布を落とす。 /弄丢了钱包视角在某人弄丢钱包这件事情上
温度を上げる。 /升高温度

一些组合范例：

自动词	他动词
集まる集合	集める收集
受かる考上	受ける赴考
植わる栽植	植える种植
終わる结束	終える做完

区分规律：

自动词
- 发音为 a段 + る e.g 集まる
- 末尾为れる e.g 現れる
- 助词为が
他动词
- 发音为 e段 + る e.g 集める
- 末尾为す e.g 現す
- 末尾为 a段 + せる e.g 合わせる
- 助词为を

8.4 动词分类：继续、瞬间、状态、形容性

ている在日语中也是一个比较特殊的表达，根据动词的不同，ている表达的意思会相差很多，因此根据这个特性可以将动词分为4个子类：

动词属性	说明	范例
继续动词	表示动词所指的动作或作用正在进行过程中	泣く、書く、渡る、飛ぶ、食べる、勉強する
瞬间动词	表示动词所指的动作成作用已经结束但其还保留着	始まる、死め、来る、汚れる、起きる
状态动词	这类动词本身就表示状态，其意义多表示存在、能力等	ある、いる、できる（会、能够）、見える、読める
形容词性动词	形容词性动总是要以“ている”的形式使用，且以这种形式表示状态、性质等	優れる、そびえる、治う、似る

8.5 动词：分句中的时

定语、宾语、补语等成分中的时

定语等成分中的时大多是相对时
- タバコを吸っている人に道を尋ねた。
也有绝对时
- わたしの前に立っていた人は、じっと壁の上の絵を見つめている。

状语成分中的时

当接续助词为“し”、“が”、“けれども“，即表示并列、对比时，或状语从句中的动词为状态动词时，分句动词用绝对时
- 洋服の生地も決めたし、靴も注文した。
当状语从句中的动词为动作性动词时，用相对时
- 彼女が急に帰国したので、みんな驚いた。/她突然回国了,大家都很惊话。
- 彼女が帰国するので、お別れ会をしてあげた。/她要回国了,所以给她开了个送别会。
当状语是假定的关系，如条件、让步等逻辑关系时，状语从句中的时多为相对时
- たとえ諦めるにしても、もう少し努カしてみるべきだった。

引用成分中的时

引用成分（包括引语、思考内容等）多保持原话的时，也就是说在句中呈现相对时
- 彼は必ず行くと言ったのに、来なかった。

8.6 动词：补助动词的时态变化

一般在看语法书的时候，语法书只会讲补助动词的基本形/辞书形：ている、てある、てしまう等。实际使用的时候，因为肯定/否定，非过去时/过去时，常体/敬体会导致补助动词产生形态变化。这些变化一般都不会记在语法书中，所以初学者看到都会不知所谓，不知道这个新玩意儿到底是什么意思。比如说：てしまいました，这个是てしまう这个补助动词的过去肯定敬体。

所以在自学的时候，需要将补助动词的て去掉，然后将剩下部分的作为一个动词，来掌握其变化，最后补回て即可。

更多的例子可以去上面7.2.x，都有构成表。举个例子：持续体7.2.2。

8.7 动词：授受表现

N4文法28「授受動詞」あげる、くれる、もらう
 N4文法29「て形+授受動詞」てあげる、てくれる、てもらう

8.7.1 授受动词

时式	语气	常体	敬体
あげる/やる	给予
非过去	肯定	あげる/やる	あげます/やります
非过去	否定	あげない/やらない	あげません/やりません
过去时	肯定	あげた/やった	あげました/やりました
过去时	否定	あげなかった/やらなかった	あげませんでした/やりませんでした
さしあげる	给予	あげる/やる的尊敬形式
非过去	肯定	さしあげる	さしあげます
非过去	否定	さしあげない	さしあげません
过去时	肯定	さしあげた	さしあげました
过去时	否定	さしあげなかった	さしあげませんでした
くれる	给予
非过去	肯定	くれる	くれます
非过去	否定	くれない	くれません
过去时	肯定	くれた	くれました
过去时	否定	くれなかった	くれませんでした
くださる	给予	くれる的尊敬形式
非过去	肯定	くださる	くださります
非过去	否定	くださらない	くださりません
过去时	肯定	くださった	くださりました
过去时	否定	くださらなかった	くださりませんでした
もらう	获得
非过去	肯定	もらう	もらいます
非过去	否定	もらわない	もらいません
过去时	肯定	もらった	もらいました
过去时	否定	もらわなかった	もらいませんでした
いただく	获得	もらう的尊敬形式
非过去	肯定	いただく	いただきます
非过去	否定	いただかない	いただません
过去时	肯定	いただいた	いただきました
过去时	否定	いただかなかった	いただきませんでした

8.7.2 内外/上下关系（方向性）

给予

关系	方向	动词	例句
内外关系	由内而外：我方给外方由外而内：外方给我方无内外：双方都为外方	あげるくれるあげる	弟は佐藤さんに本を`あげる`。佐藤さんは私に本を`くれる`。佐藤さんは鈴木さんに本を`あげる`。
上下关系	由下而上：地位低对地位高由上而下：地位高对地位低无上下：双方平辈	さしあげるくださる遵循内外关系	私は先生に本を`さしあげます`。先生は私に本を`くださりました`。私は後輩に本を`あげる`。

我方：我自己或和我有直接关系的人：自己、我的亲属、我的同事、我的朋友等
外方：对方或和对方有直接关系的人：对方、对方亲属、对方同事、对方朋友等

やる是我方给予外方（限定地位较低或晚辈）的意思，作用同あげる，但较为粗俗，一般不使用。

此外，当接收方为自己的时候，给予方永远是外方

父さんは私に本をくれる。（这里不是あげる）
私は父さんに本をあげる。

获得

もらう/いただく没有方向性，全部都是：A从B处得到某物。从高位者处获得东西的场景下，需要使用いただく。

8.7.3 句式：给予

Aは/がBにCをあげる/くれる。
- （私は）友達に辞書をもらった。/从朋友那儿得到了本辞典。
- 友達が（私に）辞書をくれた。/朋友送给我了本辞典。
A是物品的送出方
B是物品的接收方，助词用に
C是物品
あげる/くれる的使用差别参照上一节

8.7.4 句式：获得

Aは/がBに/からCをもらう。
- 弟が兄に五千円もらった。/弟弟要了哥哥5000日元
- （私の）弟が社長にネクタイをいただいた。/（我）弟弟得到经理送的领带。
A是物品的接收方
B是物品的送出方，助词用に/から
C是物品

助词：に/から

主动性与被动性
- 获得的句式只讲固定的获得行为，不讲究这个获得的主动性和被动性
  - 看一对中文示例
    - 奶奶让太郎给她读报纸。
    - 奶奶听太郎给她读报纸。
  - 虽然句子讲的都是获得，句式也都是同一句式，但实际意思还是有点不同的
- 格助词に和から可以对主动性作出大致的区分
  - に``可以（不是一定）表示要（主动）
  - から只表示（一定）收（被动）
    - （私の）弟が社長にネクタイをいただいた。/（我）弟弟得到经理送的领带。（这里に表被动，因为句意只可能是被动）
    - おばあさんは太郎に新聞を読んでもらった。/奶奶让太郎给她读报纸。（主动）
    - おばあさんは太郎から新聞を読んでもらった。/奶奶听太郎给她读报纸。（被动）
有无生命
- 无生命送出方只能用から
  - 私は会社から車をもらいました。

8.7.5 作为补助动词的授受动词

授受动词不仅可以独立使用，还可以接在动词连用形+て的后面，充当补助动词，借以表示人物之间行为的往来与恩惠关系。

太郎がおばあさんに新聞を読んでやった。/太郎为奶奶读了报纸
おばあさんは太郎に新聞を読んでもらった。/奶奶让太郎给她读了报纸。
先生が資料を集めてくださった。/老师给(我)收集资料。

“~てさしあげる”、“~てあげる”、“~~てやる”带有强烈的恩加于外的意味，因此必须谨慎使用。为他人做什么事，则常代之以表示自谦的“お~~する”等形式。

お荷物をおもちしましょうか。/让我来给您拿行李吧。

8.8 格助词：常用整理

完整的格助词语法清单可以查看速查表。时间相关的助词整理在：时间表达的助词及句式使用，地点相关的助词整理在：地点的表达。在当前章节中除了格助词之外，还会整理提示助词は，因为这个助词经常会顶替格助词的位置，所以需要弄清楚用法。

此外，一些有用的资料：

8.8.1 常用场景整理

应用场景	助词	解说	范例

| - | 主语、行为主体、称谓 |

| - | 宾语、动作对象 |

| - | 原因、理由、依据 |

| - | 变化、演变的结果 |

| - | 动作、行为的方式、状态、手段 |

| - | 材料、原料、成分 |

| - | 比较、评价的基准 |

| - | 时间表达 |

| - | 地点表达 |

| - | 其他 |

8.8.2 が与を

表示对象的“が”可以被“を”来替换
- 子どもが水を(が)欲しいって言うんですが。/孩子说想喝水呢。
谓语是表示愿望、可能的表现形式时，表示其对象的格助词可以用“を”或“が”
- 目を(が)あけられない。/睁不开眼。
- 但其中着重点不同
  - 着重对象：目が -> あけられない(眼睛睁不开)
  - 着重动作：(目をあける) -> られない(睁不开眼時)

8.8.3 に与を

这里主要讨论的是对象使用时的に与を的使用区别，作为地点时的使用相对来说区别比较清晰，不需要额外论述。

参考：

区别：

に是补格助词
- 补格助词前面的一般是补语
- 后面的谓语动词一般是自动词(不绝对)
- 补语的对象在日语的思维中，都不是实物，或不是直接接触的对象
を是宾格助词
- 宾格助词前面的一般指宾语
- 后面的谓语动词一般是他动词(不绝对)
- 宾语一般指实物，能够真实触及到的
  - 彼を倒した。
  - ご飯を食べる。
思维差异
- 電車に乗る。
  - 日本人认为，乘坐是没有宾语的，是人乘坐到车子里面，而不是车子被人乘坐。
- 山に登る。
  - 日本人认为，攀登这个词是没有宾语的，山并不是被爬，而是爬这个动作有一个方向，这个方向就是山上。
感情动词的例子不太适用于上面的解说，可能需要硬性记忆
- に：苦しむ、困る、疲れる、気づく、慣れる、酔う、驚く、飽きる、憧れる……
- を：楽しむ、愛する、悲しむ、嫌う、望む、恨む、惜しむ、憎む、好む、恐れる……
举例：更换动作的を和に
- 同一类的物品进行更换用を（实际物体，宾格）
- 不同的物品之间的更换用に（概念，补格）
  - 新年になったので、日記帳を換えた。新しいのに換えた。
  - 家に帰ると普段着に換える。
  - 大連まで飛行機で飛んで、そこから船に乗り換える。
  - 私は南門でバスを乗り換える、３番バスから１番バスに乗り換える。
がにを的一些麻烦例子
- 好恶：
  - 私は　先輩を　愛する。“爱上”
  - 私は　先輩に　憧れる。“迷恋”
  - 私は　先輩が　好きだ。“喜欢”
- 看：
  - 私は　富士山を　見る。“看”
  - 私は　富士山に　向ける。“面向”
  - 私は　富士山が　見える。“看得见”

8.8.4 は与が

“は”与“が”是两种性质完全不同的助词。

“が”接在体言或相当于体言的词语后，表示该体言是断定、存在、性质、状态、行为、動作等的主体。
“は”的作用是表示说话人突出地提出一个成分来，使之成为后面的谓语部分着重说明的对象。这个成分既可以是主语，也可以是宾语、状语、补语等。“は”既可以跟在体言后面，又可以跟在用言的活用形后。跟在体言后的“は”，可以表示主语（代替“が”）、也可以表示宾语（代替“を“）、表示补语（代替“へ”等）。

所以像下面这样的句子，“は”代替的是“を”和“に“，就不能用“が”来替换。

O この本は父が買ってくれた。/这本书是父亲给我买的
O ここは植木を置いてください。/请在这几放个花盆。

因此，所谓“は”与“が”的区别，应该只是指表示谓语主体的“が”与代替“が”提示主题的“は”的区别。

“は”用于“已知”的事物，“が”用于“未知”

当句子的着重点或疑问点在主体以外的部分时，主体后用“は”，当句子的着重点或疑问点在主体时，主体后用“が”

O 先生はどなたですか。
O どなたが先生ですか。
O あなたのはどの傘ですか。
O どの傘があなたのですか。
O 東はどちらですか。
O どちらが東ですか。
O 一陳さんは寮にいますか。一いいえ、陳さんは図書館にいます。（问句中主体后用“は”，答句中主体后也用“は”)
O ーどの傘があなたのですか。一赤いのが私のです。（问句中主体后用“が”，答句中主体后也用“が”)

试比较“私は理事長です”和“私が理事長です”。前句中用“は”表示的“私”是已知概念，“理事長です”是对于前面部分所做的说明，是就“私はどういう人か”这一问题向对方传递新的信息“理事長”。而后句中“理事長”是已知信息，听话人要知道的是“謹が理事長か”这个问题的答案，说话人对此提供“私が”这个新的信息作为回答。

“は”用于主观判断来说明某一事物（包括真理、法则、习性等），或者表示人的意志、信念、能力、习慣等，“が”用于客观描述眼前具体情景

O 太陽は東から出る。/大阳是从东方升起的
O 西安は古い都です。/西安是古都。
O わたしは每朝庭の掃除をします。/我每天早上打扫院子
O あ、雨が降ってきた。/啊,下起雨来了。
O 桜の花が咲いている。/樱花开了。
O 風が冷たいですね。/风真冷啊。

“タ焼けがきれいだ”和“タ焼けはきれいだ”这两句的不同在于，“タ焼けがきれいだ”是客观描写眼前具体情景，从这一句话可以想到它所存在的场景：仰望天空时看到彩霞，不禁脱口而出；“晚霞真美”。即指当时看到的晚霞美丽。“タ焼けはきれいだ”是对晚霞这一事物做出的一般性判断。说这句话时，不见得非要看到晚度。

包孕句或主从句中主句主语一般用“は”，从句主语一般用“が”

O あなたがこなかったのはいけなかった。/你没来，这可不好。
O 母は私が国を出るとき泣きました。/在我要离开家乡的时候，母亲哭了。
O 私が言うことをそのまま書きなさい。/把我说的话原样写下来。
O このテレビはデザインがとてもいいです。/这台电视设计的真好。
O 映画館が近ければ私も行きます。/要是电影院不远的话, 我也去。
O 雨が降っているのに外で遊んでいます。/下着雨，还在外边玩几。
O 私はうちへ帰るとすぐお風呂に入ります。/我回家后立刻洗澡。

从上面的例句可以看出：主体用“が”一般只关联到就近的谓语，主体用“は”关联到句末或全句，甚至关联到下面的句子。因此下面的句子是错误的：

X 雨は降れば行きません。/要是下雨，就不去了。
X あなたは行けと言うなら行こう。/如果你非让去,那我就去吧。

像“象は鼻が長い”这样的主谓谓语句，谓语从句主语（小主语）也有用“は”的情况，这时多表示对比或转折的语气。“象は鼻は長い”这句话就多见于“象は鼻は長い (が，目は小さい）”等表示对比的场合。

8.8.5 と的细节，与に/を的比较，以及って

って：可以理解成“って言って”省略了“言って”
- ぼくは鈴木っています。/我叫铃木。
- あとで金を渡すってだましやがった。/欺骗说什么回头再给我钱。
って：“という”、“って”有时可以表示同格
- その会社の、会長という人。/那个公司做董事长的人
- 10 年って年月がかかる。/要花 10 年的时间。
って：像提示助词一样的用法，这时相当于“とは”、“というのは”
- 北海道って広いのね。/北海道可真是辽阔啊!
- 日本って狭いんだな。/日本真是小啊
と和に
- 表示“行为、动作的共同者或对象”时，“と”和“に”都可以使用，“と”表示相互的动作，“に“表示単方向性的动作
  - 昨日駅で田中さんに (と）会いました。/昨天在车站见到了田中
  - 来年の留学のことを父に (と）話しました。/和父亲谈了明年留学的事。
- 表示“比较的基准”时，“と”和“に”也都可以使用，用“と”主要表示对等性，用“に”表示单方向性，重点在于逐渐接近对方
  - 先生と (に)よく似た人。/和老师长得很相像的人。
- 表示变化的结果
  - “AをBとする”表示将本来不是 B 的 A，一时作为 B 来用，是暂时的、表面性的变化
    - 閲覧室を教室として一週間勉強した。/把阅览室作为教室，学习了一个星期
    - 兄を先生として少し英語を習った。/把哥哥当老师，跟他多少学了些英语
  - “AをBにする”表示把 A 改造成 B，是永久的、本质性的变化。
    - 教室が足りないので、閲覧室をも教室にした。/因为教室不够、把阅览室也改造成为教室了。
    - 息子を学校の先生にした。/让儿子当了学校的老师
と和を
- 言う、思う、考える、話す、感じる、申す、存じる、書く、呼ぶ等都称作言表动词，它所表示的内容，有抽象的概念，也有具体的内容
- 抽象的概念用を
- 具体的内容用と
  - ここに電話番號を書いてください。
  - 部屋のドアに(部屋番號が)301と書いてあります。
  - 明日は良い天気になると思います。
  - 明日の天気を心配します。
  - 先生が「王さん、王さん」と呼んでいます。
  - 先生が学生の名前を呼んでいます。

8.8.6 から与で，原材料的区别

“から”和“で”都可以表示原料材料，一般说来，从原料到成品变化较少（从成品能推测出原料）时用“で”，从原料到成品变化较大（从成品很难推测出原料）时用“から”

その椅子は本でできている。/那把椅子是用木头做的。
プラスチックは石油から造る。/塑料是以石油为原料制造的。
あんな古着からこんなすてきな服をつくるとはさすがだ。/能用那样的旧衣服做出这么漂亮的衣服真了不起。

但是，也有像“酒は米でつくる”和“酒は米からつくる”这种“から”和“で都能用的情况。用“で”时着重强调米是做酒时所使用的东西，和“で”表示方法、手段是同一性质的用法，用“から”时着重强调米是生产酒的起点，在生产过程中发生变化，最后成为酒。

8.9 其他助词

个人感觉比较重要和常用的非格助词的其他助词的语法清单可以查看速查表。本章节接下来的内容会选择一些非格助词的差异点和难点进行解说。

8.9.1 て的细节：中顿、ない+て

动词连用形+て与动词连用形表示中顿用法的异同

在表示一个动作主体的动作的先后关系时，“动词连用形+て”这种形式要求前后两个动作或者都是意志动作，或者都是无意志动作。而动词连用形表示中顿时则不受这些条件的限制，前后两项可以都是意志动作或都不是意志动作，也可以其中之是意志动作而另一个不是意志动作。

O 彼女は家に帰り(O 帰って)、食事の用意にとりかかった。/她回到家，开始准备做饭，（前后两项都是意志动作)
O 田中さんは飛行場に着さ(O 着いて)、荷物の検察をうけた。/田中到达了机场接受了行李检查。（前后两项都是无意志动作）
O 田中さんは飛行場に着さ（？着いて）、家に電話をした。/田中到了机场，给家里挂了电话。（“着く”是无意志动作，“電話をする”是意志动作）
O わたしは野村に偶然に会い（？会って）、その話をした。/我偶然遇见了野村，讲了那件事。（偶然に会う”是无意志动作，“その話をする”是意志动作）

在并列两个动作主体进行的两个动作时，“动词连用形+て”要求前后两个动作必须都是有意识进行的动作，动词连用形表示中顿时可以都是有意识进行的动作，也可以都是无意中出现的动作。

O 太郎が東大にはいり（O はいって）、次郎は早大にはいった。/太郎进了东京大学，次郎进了早稻田大学，(前后都是意志动作)
O 太郎は帽子をとられ(? とられて）、次郎は服を破られた。/太郎帽子被拿走了，次郎衣服被撕破了。（前后都是无意志动作）

表示同一个动作主体进行的两个动作，而这两个不是先后发生的动作时，可以用动词连用形表示中顿的形式。很少用“动词连用形+て“的形式。

O 弟はスケートもやり(X やって)、スキーもやる。/弟弟既滑冰又滑雪
O 李さんは日本語もでき(? できて)、英語もわかる。/小李既会日语又懂英语

另外，“动词连用形+て”多用于口语中，动词连用形表示中顿多于书面语。

“なくて”的主要用法

“なくて“连接的前后两项是相对立的事物。
- O 雨が降らなくて、雪が降った。/不下雨，下雪了
- O あの人は何もしてなくて、みんなやったのは私です。/那个人什么也不千，都是我做的。
“て“表示原因、理由或以“ては”的形式表示假定条件。
- O うまく説明できなくて、困った。/不能很好地说明，真为难。
- O 雨が降らなくては田も植えられない。/不下雨的话，就种不了田（插不了秧）。

“ないで”的主要用法

后接补助用言
- O 何も聞かないでください。/请什么都别问。
- O 何もしないでいてみよう。/试一试什么都不做。
前项修饰后项
- O あの人は、人の言うことを聞かないで出て行った。/那个人也不听别人说什么就出去了。
- O 雨が降っているのに傘も差さないで步いている。/下着雨，可是却没打伞走在雨中。

如果既可以认为前项与后项是相对立的事物，又可以认为前项修饰后项的时候，则二者都可以用。

O 雨が降らなくて、雪が降った。/不下雨，下雪了。
O 雨が降らないで、雪が降った。/不下雨而下雪了。

8.9.2 ながら

在表示动作同时进行时，“ながら”要求同时进行或同时存在的两个动作的主体是同一个主体，并且表示两个动作的动词应是动作性动词而不是状态动词。在前后是同一主体，且前后动词都是动作性动词时，也要注意，瞬间动词一般是不后续“ながら”的。

下面这几个例句是错误的

X 雨が降っていながら、風が吹いています。（不是同一主体）
X 喫茶店から音楽が聞こえながら、みんなコーヒーを飲んでいます。（“聞こえる”是状态词）
X 電車に乗りながら新聞を読む。（“（電車に）乗る”是瞬间动词）

同时进行或同时存在的两个动作，在有的句子中，前项和后项互换意思上也没有太大的差异，如

O 音楽を聞きながら、コーヒーを飲む。
O コーヒーを飲みながら、音楽を聞く。

但是，一般地说，“ながら”句型的重点在后项，前项修饰、限定后项，从逻辑上说，前项从属于后项。因此打破了这种关系的句子就显得不自然。

X バスを待ちながら、体が寒さにふるえてしまった。
O 寒さにふるえながら、バスを待つ。
X 部屋へ帰って休みながら、コーヒーを飲む。
O コーヒーを飲みながら、休む。

8.9.3 ても/でも连续助词

在口语中，“ても”接在形容词或形容词型活用助动词后面时可以说成“っても”以表示强调

O 寒くっても平気です。/即使冷,也不要景。
O 国へ帰りたくってもニ年間は帰らないつもりです。/即使想回国，两年内也不准备回国。

“っても”还可以接在用言或助动词终止形后面，但这是“~と言っても”的缩略形式。

O 帰るっても、今からではもう遅い。/即使说要回去,现在也晚了。
O 暑いっても、私の国に比べれば、それほどではありません。/说这儿热，可和我们国家相比，就不算多热。

8.9.4 でも提示助词

提示助词“でも”与“格助词で+提示助词も”的区分有时并不十分明显。

A: デバートでは売っていませんか。/在百货商店里没有卖的吗?
B: デバートでも売っていますよ。/在百货商店里也有卖的呀。

上句中的“でも”一般认为是“格助调で+提示助词も”

O これなら田舎でも売っています。/如果是这个的话,乡下也有卖的。
O このごろのラジオは感度がよくて、山の中でもよく聞こえる。/现在的收音机接收信号好，即使在山里面也能听清楚。

这两句中的“でも”就很难说清是提出极端事例的提示助词，还是“格助词で+提示助词も”。当然，如果上例中“でも”前有“で“，那么就很明确了，是“格助词で+提示助词でも”。

O これなら田舎ででも売っています。/如果是这个的话,乡下都有卖的。
O このごろのラジオは感度がよくて、山の中ででもよく聞こえる。/现在的收音机接收信号好，即使在山里面也能听清楚。

8.9.5 とか

对并列助词“とか”和格助词“と”与副助词“か”叠用的“とか”需要加以区别。

叠用起来的“とか”中的“と”是表示称谓、叙述的内容的，因此多和“言う”“話す”等词一起使用。下面的例子均是格助词“と“和副助词“か”叠用的“とか”

O 木村さんとかいう方から電話がありました。/有个好象叫木村的打来过电话。
O ガラスのドアにひびが入っているとか言っている。/说什么玻璃门上有了裂纹。
O 行くとか行かないとかいって、ぐずぐずしているんですよ。/又说去又说不去的，在那儿犹豫着呢。

8.10 补助形容词

在语法讲解中也较常出现：接在其它用言后起补助作用的形容词叫作补助形容词。补助形容词有“ない“、“ほしい”、“いい (よい)“。主要用法是接在て/で之后。

X. 速查表

X.I 体时态

| 分类 | 表达 | 例句 | 注解

:--- | :--- | :--- | :--- | :--- 体 | 持续体 | ている | 今、市内の病院で働いている | 视点在动作持续或反复的过程中，无起始和终止体 | 持续体 | てくる | とにかく私は苦労してきた | 同ている，但明确了发话时间，常用过去时体 | 持续体 | ていく | この子は私ー人の力で育てていきます | 同ている，但明确了发话时间，常用非过去时体 | 持续体 | つつある | 世界は変わりつつある(瞬间)
台風はゆっくり北上しつつある(继续) | 渐进性持续，多是瞬间动词
也可是继续动词，但不常见体 | 存续体 | ている | 井上先生はいま中国に行っている
桜の木が枯れている | “瞬间动词+ている”构成状态存续意义的存续体
这种方式构成的存续体，表明动作行为已经发生，
但它所造成的状态仍然存在体 | 存续体 | ている | 井上先生は中国に何回も行っている | “动词+ている”还可以表示人们的经历、事件的记录体 | 存续体 | てある | 窸が開けてある | 他动词后，过去动作、行为的结果还保留着体 | 完成体 | てしまう | この小説を今週中に読んでしまう
きれいに財産を使っちゃう | 连用形+てしまう
可约音成“ちゃう”或“ちまう” 体 | 准备体 | ておく | 自転車はもう買っておいた | 连用形+ておく
必须是意志动词体 | 即将体 | - | 式は間もなく終わろうとしている
もう食べるばかりになっている
出かけるところだ
彼女は今にも溺れそうだった | ~う (よう）とする
~するばかりだ
~するところだ
~そうだ体 | 起始体 | - | 学生たちは解答を書き始めた
止まっていたバスが動き出した
雨が降ってきた | 意志/非意志+始める
非意志+出す
~てくる：事态出现变化，即开始时 | 非过去 | 确定将来 | 明日必ず行きます | 继续动词和瞬间动词的非过去时形态时 | 非过去 | 反复行为
现在 | 毎日指を折って椅子の数を数える
夜、料理クラスへ通っている | 继续动词和动词持续体非过去时形式，
均可表示现在反复进行的或习惯性的动作、行为时 | 非过去 | 现在状态 | 花子さんは飛行機の操縱ができる
池までの小径が曲がっている
隣の犬が死んでいる | 状态动词、动词存续体形容词性动词+ている
的非过去时形式，均表示现存的状态时 | 非过去 | 概念真理 | 地球が回る | 表示超越时间观念的概念、规律、真理、说明等时 | 过去时 | 过去行为 | 昨日ここで交通事故が起った | 过去某个时刻的行为，用“动态动词连用形+た”表示时 | 过去时 | 反复行为
过去 | 昔はよくここで泳いだ
暇な時は山登りに行ったものだ | 用“动态动词连用形+た”或动词持续体的过去时表示，
有回忆的意味时 | 过去时 | 过去状态 | 三日前はこの窓ガラスが割れていた
昔、ここにはたくさんの湖があった
以前太っていたが、最近やせてきた | 用“状态动词连用形+た”、瞬间动词的存续体过去时、
“形容词性动词+ていた”表示态 | 被动态 | 直接被动 | 太郎が次郎に英語を教える(主动)
次郎が太郎に英語を教えられる
王さんが李さんに辞書を渡す(主动)
李さんが王さんから辞書を渡された | 可以还原为主动句来说明
构成直接被动态的动词都是``他动词
“~に”格成分看作人物宾语
“~を”格成分看作事物宾语态 | 被动态 | 间接被动 | 私は帰る途中、雨に降られた(自动)
幼い時に、父に死なれた(自动)
電車の中で足を踏まれた(他动)
電車の中で(誰かが)足を踏んだ(主动句) | 间接被动句主语不是动作的直接承受者，
而是间接地受到与之没有直接关系的事情的影响
分为自动词和他动词的间接被动句
自动词的间接被动句无法还原成主动句态 | 使动态 | - | 先生が彼に論文を書かせる(他动命令)
彼にかってに言わせておこう(他动放任)
子どもを9時までに寝させる(自动强制)
子どもに一人で大通りを
渡らせるのは危ない(自动放任) | 他动词，使动对象都用“に”
自动词，强制性用“を”，非强制性用“に” 态 | 使动态 | 被使动态 | (弟が借りた)借金を払わせられた | 是使动态的被动态
行为不是自觉主动的，而是被迫的、不情愿的态 | 可能态 | - | 日本語を話すことができる
日本語が話せる
調子が悪くて、私には大声で話せない | 惯用型“~ことができる”不发生对象的格的转换
可能对象用格助词“が”表示
能动主体有时用格助词“に”表示态 | 自发态 | - | 雪が降ると、故郷のことが思い出される
故郷を思い出すと、勇気が出る | 动作对象如果出现，也可以是“が”的形式
表示不由自主地产生某种行为或结果，与人为动作不同

X.II 动词活用形

活用形	用例	范式	范例
未然形	否定	ない	雨が`降らない`。
未然形	使役	させる (せる）	弟を買い物に`行かせ`た。
未然形	被动	られる (れる）	彼は父に`叱られ`た。
未然形	可能	られる (れる）	それは`食べられる`。
未然形	尊敬	られる (れる）	先生が`帰られ`た。
未然形	意志和推测	う(よう) 一段动词和サ变动词+まい	粘土で人形を`作ろう`。あんなばかなことは二度と`しまい`。
连用形	构词用法		`動き`が激しい `使い`道 `流れ`込む `聞き`辛い魔法`使い`
连用形	中顿		流れは山を`下り`、谷を`走り`、野をよこぎる。
连用形	后接助动词	ます敬体た过去、完了、状态等たい、たがる愿望そうだ可能性	僕は君の幸せを`望みます`。やっばり、かぎはここに`あった`。今度は立派な論文を`書きたい`。不景気で会社が`つぶれそうだ`。
连用形	后接格助词	に目的	朝早く鮭を`釣りに`行った。
连用形	后接接续助词	てながらつつてもたってては	春が`来て`、雪が溶けた。友と`語りつつ`酒を飲む。
连用形	后接并列助词	たり	ー日中`踊ったり`、`歌ったり`した。
连用形	后接提示助词	はもでもさえ	御恩は決して`忘れは`しない。駅の案内を人々はほとんど`聞きも`、`見も`しません。
连用形	后接语气助词	な	危ないから、気を`つけな`。
终止形	结句		この花はいい匂いが`する`。
终止形	后接助动词	そうだらしいだろう (でしょう）	彼は留学の許可を得るため両親を`説得するそうだ`。新人を入れてチームの若返しを`図るらしい`。
终止形	后接助动词	五段动词和サ变动词+まい	わざわざ嵐の中で登山をするものは`あるまい`。
终止形	后接并列助词	か	`行くか`行かないか迷っている。
终止形	后接语气助词	かなねよなぁさ	転んだくらいで泣く奴が`あるか`。急ぐから、僕はもう`帰るよ`。
终止形	后接接续助词	がけれどもとから	私は車の連転が`できるが`、兄はできない。会社は今危機に`あるけれども`、つぶれないと思う。
连体形	后接体言	作为定语	`流れる水`と`噴き上げる水`。
连体形	后接助动词	ようだみたいだ	彼も最近新しい機械を工夫して`いるみたいだ`。
连体形	后接接续助词	のでのに	日本語だけで十分に`表せるのに`、なぜ…
连体形	后接副助词	だけくらいほどばかり	人生には、`遭難するぐらい`惨めなことはない。 `眺めるだけ`なら、お金は要らない。
连体形	后接提示助词	しか+否定	ここまで来たら、`やるしか`ありません。
连体形	后接语气助词	の	くずぐずしないで、さっさと`するの`。
连体形	后接形式名词	こともののはずわけため	ここまで来て登山を`中止するわけ`にはいかない。たいていのことは日本語で十分`表せるはず`だ。
假定形	可能‧条件	ば	ちりも`積もれば`山となる。
命令形	命令		僕の話を`聞け`！

X.III 动词活用

分类	活用形	规律	原形	变形
五段	未然形	否定：转`あ`段推量：转`お`段	行く	いか・ないいこ・う
五段	连用形	转`い`段	行く	いき・ます
五段	终止形	不变	行く	行く
五段	连体形	不变	行く	行くこと
五段	假定形	转`え`段	行く	いけ・ば
五段	命令形	转`え`段	行く	いけ！
一段	未然形	去`る`	見る	み・ない
一段	连用形	去`る`	見る	み・ます
一段	终止形	不变	見る	見る
一段	连体形	不变	見る	見ること
一段	假定形	`る`换`れ`	見る	み・れば
一段	命令形	`る`换`ろ/よ`	見る	み・ろ/よ
サ变	未然形	词干加`し`	勉強する	勉強し・ない/よう
サ变	连用形	词干加`し`	勉強する	勉強し・ましょう
サ变	终止形	不变	勉強する	勉強する
サ变	连体形	不变	勉強する	勉強すること
サ变	假定形	词干加`すれば`	勉強する	勉強・すれば
サ变	命令形	词干加`しろ/せよ`	勉強する	勉強・しろ/せよ
カ变	未然形	-	来る	こ・ない/よう
カ变	连用形	-	来る	き・ます
カ变	终止形	-	来る	くる
カ变	连体形	-	来る	くること
カ变	假定形	-	来る	くれば
カ变	命令形	-	来る	こい

X.IV 动词音便

只限：

五段动词
连用形
- 后接助动词た
- 或
- 后接续助词て、ては、たも、たん、たって

分类	尾音	规律	原形	连用形	变形
促音便	うつる	转促音`っ`	使う待つ乗る	使い待ち乗り	つか`っ`・てま`っ`・たの`っ`・て
拨音便	ぬぶむ	转`ん` `ん`后假名`浊化` て → で、た → だ	死ぬ呼ぶ飲む	死に呼び飲み	し`ん`・`で` よ`ん`・`だ` の`ん`・`で`
イ音便	くぐ	转`い` `ぎ`的情况い后假名`浊化` て → で、た → だ	書く嗅ぐ	書き嗅ぎ	か`い`・てか`い`・`で`

X.V 形容词活用

活用形	规律	范例
未然形	去い + かろ+推量助动词うかった（过去式）	京都の桜は美し`かろう`。昨日はとっても楽し`かった`。
连用形	去い + く + 名词/副词て（中止接续）ない（否定）なる（表变化）	美味し`くて`たまらない。彼女は全然美し`くない`。だんだん暑`くなる`。
终止形	不变	美味しい
连体形	不变	美味しいご飯
假定形	去い + ければ + ···	楽し`ければ`···

X.VI 形容词语法

活用形	规则	语法作用	范例
未然形	去い+かろ	表示推测	奨学金だけでは生活が`苦しかろ`う。
连用形	去い+く	用言前作状语	いつものように、`つまらなく`家に帰った。
连用形	去い+くなる去い+くする	表变化	なる类似自动词，表自然变化：人口が増え、市場も`大きく`なった。する类似他动词，表人为变化
连用形	去い+く	中顿	お父さんは、僕たちに`きびしく`やさしくて、とても心が広かった。
连用形	去い+くない	表否定	日本料理は明るい所で白ちゃけた器で食べては`うまく`ない。
连用形	去い+くて去い+くても去い+くては	表并列表原因表转折表条件	`大きく`て、`薄く`て楽しそうな絵がいっばい。天気が`悪く`てほとんど泳げなかった。どんなに`寒く`ても・・・あんなに`やかましく`ては、話もよく聞きとれないだろう。
连用形	去い+くは去い+くも	增添语法意义	ここから見るとそんなに`高く`は感じられません。僕は`若く`もなく、ハンサムでもない。
连用形	去い+かった	表过去完了	高原に春の訪れは`遅かっ`た。
连用形	去い+かったり	表并列	値段は`高かっ`たり、`安かっ`たりして、季節によって違います。
终止形	-	作谓语结句	最近のたばこは昔のに比べるとずいぶん`やわらかい`。
终止形	+から +けれども +し	表原因表转折中顿	今度のお客さまは食べ物に`うるさい`から、よくよく注意しなさい。咲いているあいだは`美しい`けれども、枯れると汚いね。頭も`痛い`し、手足も`だるい`し、少し目まいもする。
终止形	+か +よ/ね	表疑问表语气	ひどく`痛い`か。映画より小説のほうが`面白い`よ/ね。
终止形	+そうだ +らしい	表传闻表测助	日本の生徒は勉強時間が`少ない`そうだ。ストレスは目に`悪い`らしい。
连体形	-	体言前作定语	`強い`日差しが照り付けて、各地で軒並み気温が三十度を超えた。
连体形	+の/もの/こと等	转体言、惯用型	語学というものは、とても`楽しい`ものです。
连体形	+ので +のに	表原因表转折	山に`近い`ので、昼間はひどく暑い。ふだんは無ロで`おとなしい`のに、・・・
连体形	+だけ +ほど	表转折表程度	勉強が`忙しい`だけに体をいっそう大切にしなければならない。遠くから見ても`眩しい`ほど黄色に輝いているものばかりです。
连体形	+ようだ/みたいだ	表比喻	やはり本店の方が、`おいしい`ような気がします。
假定形	去い+ければ	表假定条件	天気が`よけれ`ば、スケッチに出かける。
仅词干	词干+名词等	构词法	近道、大きさ、荒っぽい、真っ暗
仅词干	-	作谓语表感叹	ああ、`から`。おお、`おそろし`。
仅词干	词干+そうだ	表样态	`苦し`そうに顔をゆがめている。

X.VII 形容动词活用

活用形	规律	范例
未然形	原形 + ろう(推测)	綺麗だ`ろう`。
连用形	去だ + だった(过去) ではない(否定) に(副词) に成る(になる, 表变化)	綺麗`ではない`。
终止形	不变	綺麗だ。
连体形	去だ + な + ···	綺麗な`もの`。
假定形	去だ + なら + ···	綺麗`なら`···

X.VIII 形容动词语法

活用形	规则	语法作用	范例
未然形	+だろう	表推测	みんなで話し合いをしないと`駄目だろ`う。
连用形	去だ+で	中顿	`便利で`快適な生活の裏で、増え続けるエネルギー消費。
连用形	去だ+で(は/も)ない	表否定	あまり`好きで`はないが、さほど`嫌いで`もない。
连用形	去だ+では去だ+でも	表假定条件表让步条件	話があまり`簡単で`は分りにくいだろうから、少し長くやりましょう。海は`穏やかで`も船で行くのはよそう。
连用形	去だ+に	接用言作状语	その内容を`十分に`審査して、業者を決定いたします。
连用形	去だ+になる去だ+にする	表变化	なる类似自动词，表客观变化：運動をすることによって、骨が`丈夫に`なった。する类似他动词，表主观变化科学の進歩が人間を`幸福に`することを疑わなかった。
连用形	去だ+だった	表过去完了	あの山は`有名だっ`たかもしれませんが、今・・・
连用形	去だ+だったり	表并列	このへんは時間によって`静かだっ`たり、`にぎやかだっ`たりです。
终止形	-	作谓语结句	詩を書いたり小説を読んだりするのも`倫快だ`。
终止形	+から +けれども +し	表原因表转折中顿	・・・駅からも遠くて`不便だ`から、引越すことにした。仕事は`困難だ`けれども最後までがんばらなければならない。砂浜も軟らかいし、波も静かで、水も`きれいだ`し、海水浴・・・
终止形	+そうだ	表传闻	日本語は全然`だめだ`そうですよ。
连体形	去だ+な	接体言作定语	弟に、`無邪気な`笑顔が戻っていた。
连体形	去だ+なの/こと/もの	转体言、惯用型	私が`大好きな`のは、自然の美しさです。
连体形	去だ+なので去だ+なのに	表原因表转折	和菓子が`好きな`ので、よく和菓子屋さんを探しに行きます。日本語で修士論文を書くのも`大変な`のに、・・・
连体形	去だ+なだけ去だ+なほど	表转折表程度	`速やかな`だけでなしに、携帯と操作もはなはだ便利である。 `不思議な`ほど鮮明に覚えている。
连体形	去だ+なようだ	表比喻	人間は体に栄養が`必要な`ように心にも栄養がいるのです。
连体形	去だ+な	结句表感叹	そんな。`ばかな`。
假定形	去だ+なら	表假定条件	天候が`順調ならば`航空ショーが行われる。
仅词干	词干+名词等	构成复合词	好き嫌い、得意顔、心静か、負けず嫌い
仅词干	词干+前缀/后缀	构成派生词	お大事、無器用、もの静か、豊かさ、新鮮み、得意げ、不思議がる
仅词干	-	作谓语表感叹	あら、`すてき`!
仅词干	词干+そうだ词干+らしい	表样态表推测	切符が`大事`そうにしっかり握られていた。日本人はむしろそれが`好き`らしいです。
仅词干	-	作名词用	子供達に対してつねに`親切`を示すことは、一種の文明です。

X.IX 格助词语法

| 用法 | 范例

X.X 其他常用助词语法

| 用法 | 范例

XI. 常用表达

数字的表达

日语数字 WIKI

数字	音读	训读	数字	音读	训读
0	れい/ゼロ	まる
1	いち	ひと(つ)	10	じゅう	とおそ(用于30-90整十的训读)
2	に	ふた(つ)	20	にじゅう	はた(ち)
3	さん	み(っつ)	30	さんじゅう	みそ
4	し/よん/よ	よ(っつ)	40	よんじゅう	よそ
5	ご	いつ(つ)	50	ごじゅう	いそ
6	ろく	む(っつ)	60	ろくじゅう	むそ
7	しち/なな	なな(つ)	70	ななじゅう	ななそ
8	はち	や(っつ)	80	はちじゅう	やそ
9	く/きゅう	ここの(つ)	90	きゅうじゅう	ここのそ
100	ひゃく	もも	1000	せん	ち
200	にひゃく		2000	にせん
300	さんびゃく		3000	さんぜん
600	ろっぴゃく
800	はっぴゃく		8000	はっせん
一万	いちまん	よろず
一億	いちおく
一兆	いっちょ

点念作：てん
零的用法：一般数字或单独出现时念为れい，车牌或房间号码时念为まる，电话号码则大多念为ゼロ

连贯的数数：升序

イチ、ニ、サン、シ、ゴ、ロク、シチ、ハチ、ク、ジュウ

连贯的数数：降序

ジュウ、キュウ、ハチ、ナナ、ロク、ゴ、ヨン、サン、ニ、イチ

数字4的发音规则

在日语数字里面，4可以说是发音最复杂的数字之一。现代日语里面常用的发音就有「し・よっ・よん・よ」四种，而其中以「よん」最为常见，「よ」次之。而「し」只出现在「四月」这个单词中，「よっ」只出现在「四日」这个数词中，其余都读「よん」或「よ」。

4后续助数词的第一个假名若是元音或是「な」行假名的话，和「よん」连在一起读有些拗口，所以这种情况一般不读「よん」，而读「よ」。如：4和下列助数词在一起时一般读「よ」：人、年：四人（よにん）、四年（よねん）。当4后续助数词的第一个假名是「じ」时常读「よ」：字、次：四字（よじ）、四次（よじ）。

量词的表达

量词的促音变化

数字	`か行`	发音	`さ行`	发音	`た行`	发音	`は行`	发音
`1`	１回	いっかい	１歳	いっさい	１着	いっちゃく	１分	いっふん
`6`	６回	ろっかい	６歳	`ろく`さい	６着	`ろく`ちゃく	６分	ろっふん
`8`	８回	はっかい	８歳	はっさい	８着	はっちゃく	８分	はっふん
`10`	１０回	じゅっかい	１０歳	じゅっさい	１０着	じゅっちゃく	１０分	じゅっぷん

6在さ行和た行不发生变化，仍旧是ろく
は行的量词搭配数字1、6、8、10时，还会从原本的发音は变成ぱ

常用量词

量词/意思	1 6	2 7	3 8	4 9	5 10	几

/ 个数 | ひとつ | ふたつ | みっつ | よっつ | いつつ |

| むっつ | ななつ | やっつ | ここのつ | とお | いくつ

/ 人数 | ひとり | ふたり | さんにん | よにん | ごにん |

算数计算

四则运算

四則計算（しそくけいさん）：四则运算
- 足し算（たしざん）：加法
- 引き算（ひきざん）：减法
- 掛け算（かけざん）：乘法
- 割り算（わりざん）：除法
加減乗除（かげんじょうじょ）
四則演算（しそくえんざん）

加减乘除

=：イコール、は
+：足す（たす）、プラス
-：引く（ひく）、マイナス
X：かける
/：わる

例子

5x4/2+3-6=7
- ご　かける　よん　わる　に　たす　さん　ひく　ろく　は/イコール　なな
6+2x3-8/4=10
- ろく　たす　に　かける　さん　ひく　はち　わる　よん　は　じゅう

时间日期的表达

时刻

时刻	发音	时刻	发音	时刻	发音
１時	いちじ	２時	にじ	３時	さんじ
４時	よじ	５時	ごじ	６時	ろくじ
７時	しちじ	８時	はちじ	９時	くじ
１０時	じゅうじ	１１時	じゅういちじ	１２時	じゅうにじ
０時	れいじ	何時	なんじ

日语在描述13时这样的时间点时，使用的是：午後一時（ごごいちじ）这样的方式。

时刻	发音	时刻	发音	时刻	发音
１分	いっ`ぷ`ん	２分	にふん	３分	さん`ぷ`ん
４分	よん`ぷ`ん	５分	ごふん	６分	ろっ`ぷ`ん
７分	ななふん	８分	はっ`ぷ`ん	９分	きゅうふん
１０分	じゅう`ぷ`ん
１１分	じゅういっ`ぷ`ん	１２分	じゅうにふん	１３分	じゅうさんぷん
１４分	じゅうよぷん	１５分	じゅうごふん
３０分	さんじゅっ`ぷ`ん	４５分	よんじゅうごふん	何分	なん`ぷ`ん

星期

星期	发音	翻译
日曜日	にちようび	星期日
月曜日	げつようび	星期一
火曜日	かようび	星期二
水曜日	すいようび	星期三
木曜日	もくようび	星期四
金曜日	きんようび	星期五
土曜日	どようび	星期六
何曜日	なんようび	星期几

月份

月份	发音	月份	发音	月份	发音
１月	いちがつ	２月	にがつ	３月	さんがつ
４月	`し`がつ	５月	ごがつ	６月	ろくがつ
７月	`しち`がつ	８月	はちがつ	９月	`く`がつ
１０月	じゅうがつ	１１月	じゅういちがつ	１２月	じゅうにがつ
何月	なんがつ

日历

日曜日	月曜日	火曜日	水曜日	木曜日	金曜日	土曜日
1	2	3	4	5	6	7
`ついたち`	`ふつか`	`みっか`	`よっか`	`いつか`	`むいか`	`なのか`
8	9	10	11	12	13	14
`ようか`	`ここのか`	`とおか`	じゅういちにち	じゅうににち	じゅうさんにち	`じゅうよっか`
15	16	17	18	19	20	21
じゅうごにち	じゅうろくにち	じゅうしちにち	じゅうはちにち	じゅうくにち	`はつか`	にじゅういちにち
22	23	24	25	26	27	28
にじゅうににち	にじゅうさんにち	`にじゅうよっか`	にじゅうごにち	にじゅうろくにち	にじゅうしちにち	にじゅうはちにち
29	30	31
にじゅうくにち	さんじゅうにち	さんじゅういちにち

何日ですか（なんにちですか）

其他时间词汇

时间	发音	翻译	时间	发音	翻译	时间	发音	翻译
おととい		前天	昨日	きのう	昨天	今日	きょう	今天
明日	あした	明天	明後日	あさって	后天	毎日	まいにち	每天
おとといの朝	あさ	前天早晨	昨日の朝	あさ	昨天早晨	今朝	けさ	今天早上
明日の朝	あさ	明天早晨	明後日の朝	あさ	后天早晨	毎朝	まいあさ	每天早上
おとといの晩	ばん	前天晚上	昨夜	ゆうべ	昨天晚上	今晩	こんばん	今天晚上
明日の晩	ばん	明天晚上	明後日の晩	ばん	后天晚上	毎晩	まいばん	每天晚上
先々週	せんせんしゅう	上上周	先週	せんしゅう	上周	今週	こんしゅう	本周
来週	らいしゅう	下周	再来週	さらいしゅう	下下周	毎週	まいしゅう	每周
先々月	せんせんげつ	上上月	先月	せんげつ	上月	今月	こんげつ	本月
来月	らいげつ	下个月	再来月	さらいげつ	下下个月	毎月	まいつき	每月
一昨年	おととし	前年	去年	きょねん	去年	今年	ことし	今年
来年	らいねん	明年	再来年	さらいねん	后年	毎年	まいとし	每年

时间表达的助词及句式使用

时间的表述一般根据长度分为：

时间点：对应瞬间动词
时间段：对应继续动词

同时要理解的是，时间点和时间段的概念的概念是相对的：

昨日、一日でずっと宿題をしていて、疲れたよ。
- 学习时间是一天，作为参照的自然时长也是一天，因此为时间段
秋に結婚するつもりです。
- 决定秋天（的某一天）结婚，时间长度为一天，作为参照的自然时长为一个季节，因此为时间点

助词表及范例：

助词	语义	动词	范例
に	时间点	瞬间	３時`に`駅で待ち合わせる。
で	时间段	继续	新幹線は3時間`で`東京・大阪間を走る。
で	期限	瞬间	演説はあと一時間くらい`で`終わります。
から	时间开始	继续	朝`から`彼を待っている。
まで	时间结束	继续	入学申し込みの締め切りは月末`まで`です。
までに	截止期限	瞬间	子どもを９時`までに`寝させる。

疑难点分析：

行为的「前、后」
- 前面用に：ご飯の前に、手を洗います。
- 后面用で：手を洗った後で、食事をします。

地点的表达

助词	语义	范例
に	存在的场所	動物園`に`パンダがいます。
に	动作的目标、着落点	修学旅行で関西`に`行った。彼はおつりをポケット`に`入れました。
で	动作，行为发生的场所	菊地さんのお宅`で`パーティーを開きます。
を	动作经过的场所动作离开的地点	電車道`を`歩いて来る。姉は23歳の時、国`を`出ました。

疑难点分析

交通工具
- 上车用に：毎日バスに乗って出勤します。
- 下车用を：バスを降りて１０分歩くと学校に着きます。
勤める/働く
- 勤める用に：私は銀行に勤めています。
- 働く用で：兄は父の會社で働いています。
趋向移动
- 后续的动词是表示趋向的移动动词时，动词的到达点可以用“に“、“へ”表示，也可以用“まで”表示。
  - 時間がなかったので、駅に(へ/まで)自転車で行った。/没有时间了,就骑自行车去了车站。
- 但是，“まで”暗含有到达的不是最终目的地，而是中途一点的意思
  - 京駅まで (? に/?へ)電車で行って地下鉄に乗り換えた。/乘电车到东京站换采了地铁。

问路的表达

…

并列关系、多项动作（多个目标）的表达

在实际使用中，经常会遇到稍微复杂点的情况，需要描述多个要素构成一个表达，或举例多个内容等，这种时候就需要用到这里整理的表达方法了。

词	条目	注解
と	类型	并列助词
と	接续	接在`体言`、相当于体言的词语后。在引用思考、叙述的内容时，也可接在用言、助动词后。此外，还可接在某些副词后。
と	解说	名词と名词，A和B 用于数量较少情况下的`全部列举`
と	范例	その村の川の水`と`池の水はきれいです。ピーマン`と`たまねぎが大嫌い。
に	类型	并列助词
に	接续	接在`体言`、相当于体言的词后。最后一个体言后不再加“に“。
に	解说	名词に名词，A和B 表示`添加性`的`并列关系`（全部列举）。 “に”是累加地列举全部事物，但可以表示对比、对照的并列关系，而“と”是把全部的事物作为个整体一起列举出来
に	范例	インクは黒いの`に`青いの`に`赤いのがある。白い砂浜`に`緑の松林が何とも言えない美しさだ。
や	类型	并列助词
や	接续	接在`体言`、相当于体言的词语后。や只能接体言。
や	解说	名词や名词や名词、名词や名词など，A和B和C（等/之类）用于数量较多情况下的`列举`，但仅只是全体中的一部分，类似举例
や	范例	太郎`や`次郎`や`花子などが私たちの同級生だ。新聞`や`テレビなどで、その事件のことを知った。
も	类型	提示助词
も	接续	接在体言、相当于体言的词语、用言及部分助动词的连用形、部分副词、部分助词之后可顶替主格助词“が”提示主语，顶替宾格助词“を”或与“を”重叠使用提示宾语，与补格助词重叠使用（也可顶替表示时间和位置的“に“）提示补语，也可以接在时间名词、方位名词、数词、部分副助词、部分副词后提示状语
も	解说	AもBも+谓语；Aも+谓语、Bも+谓语，A和B都提示两个或两个以上的类似事物，表示它们的情况相同，或是同一倾向
も	范例	りんご`も`オレンジ`も`果物です。このホテルから山`も`見えれば、湖`も`見えます。
て	类型	连续助词
て	接续	接在动词、形容词及动词型活用助动词、形容词型活用助动词连用形后
て	解说	AてBてCて，既A又B又C、又A又B又C て的并列描述多用在形容/形容动词上（形容动词时转成で），要注意同表达形式也可以描述前后比较关系，需要注意区分动词的情况多为描述行为的前后顺序执行，一般不适用于并列描述
て	范例	ここは広くて、便利です。田中先生は親切で優しいです。大きくて美味しくて新鮮なりんごを５つ買いました。夏は暑く`て`冬は寒いです。(这里是比较) 弟は朝ご飯を食べ`て`学校へ行きました。(这里是先后顺序)
とか	类型	并列助词
とか	接续	接在体言、相当于体言的词组和用言、助动词终止形后。并列体言则最后一个“とか”可以省略，并列用言时不能省略
とか	解说	词とか词とか词，A啦B啦C啦，A或者B或者C 表示`举例性并列`，兼有“や”和“か”的意义，注意该句式举例的意味很强
とか	范例	陳さん`とか`王さん`とか`には話したくありません。暇のときは散歩する`とか`、スポーツをする`とか`します。
やら	类型	并列助词
やら	接续	接在体言、相当于体言的词语和用言、助动词连体形后。用“やら”列举时，所并列的最后一个词后一定还要用一个“やら”
やら	解说	词とか词とか词，A啦B啦C啦，A或者B或者C 表示`举例性并列`。大多会用在当面临太多选择或想法，而无法下定决心或理出头绪时使用。
やら	范例	藤井`やら`松村`やら`から問い合わせの手紙が来た。赤いの`やら`、青いの`やら`、きれいなネクタイをたくさん持っている。
だの	类型	并列助词
だの	接续	接在体言、相当于体言的词语和用言、助动词终止形（形容动词、形容动词型活用助动词的词干）后。最后的“だの”有时可省略，多用“だのなど”的句型。
だの	解说	词だの词だの词、AだのBなど，A啦B啦C啦，A或者B或者C 表示`举例性并列`。带有比较粗俗的语感，郑重的文章中不用。说话者大多会带有「不满或责备的情绪」。
だの	范例	くだもの`だの`、おかし`だの`食べすぎたので、おなかが痛い。頭が痛い`だの`体がだるい`など`、怠ける口実ばかり探している。
か	类型	并列助词
か	接续	接在体言、相当于体言的词语和用言、助动词连体型后。 “か”并列体言时最后一个“か”一般可省略； “か”并列用言时，一般不省略。
か	解说	AかBかC，A还是B或者C 表示`两者择一`或`数者择一`的关系。
か	范例	あなた`か`私が行くべきだ。コーヒー色`か`鼠色`か`に染めてごらん。
なり	类型	并列助词
なり	接续	主要接在体言、相当于体言的词语后，也可以接在动词、形容词后。
なり	解说	AなりBなりC，A还是B还是C 以`举例的方式`表示`数者择一`的并列关系。选择的结果可`不限于`列举的事物。
なり	范例	お茶`なり`コーヒー`なり`(を)お好きなものをどうぞ。東京へ`なり`大阪へ`なり`早く行っておいでなさい。
でも	类型	提示助词
でも	接续	接在体言、相当于体言的词语、用言及部分助动词的连用形、部分副词、部分助词后。可顶替主格助词“が”提示主语，顶替宾格助词“を”提示宾语，与补格助词重叠使用提示补语，也可以接在时间名词、方位名词、数词、部分副助词、部分副词后提示状语
でも	解说	AでもBでもCでも，无论A还是B或者C、A也好B也好C也好表示`举例`，该句式在仅只有一个的时候也可以使用
でも	范例	本`でも`読んで待っていてください。新聞`でも`雑誌`でも`いいから時間つぶしに貸してくださいませんか。
だって	类型	提示助词
だって	接续	接在`体言`、相当于体言的词语、部分副词、部分助词后。可以顶替主格助词“が”提示主语，顶替宾格助词“を”提示宾语，可以与补格助词重叠使用提示补语，也可以接在时间名词、方位名词、数词、部分副助词、部分副词后提示状语
だって	解说	AだってBだってCだって，无论A还是B还是C “だって”的用法和“でも”相似，但和“でも”相比，多用在比较随便、亲切的谈话中。 `举例性地提示`同类事物中的几个
だって	范例	マンション`だって`車`だって`、みんな親に買ってもらったものだ。映画`だって`芝居`だって`君の好きなほうに連れていってあげるよ。
し	类型	连续助词
し	接续	接在`用言`、助动词的终止形后面；只需要连接中的し，最后一个一般省略
し	解说	Aし、B；Aし、Bも；Aし、Bし、C，既A又B、又A又B、既A又B且C 常与“も”呼应使用。表示两个或两个以上的事项同时存在表示同时存在的事项是后续句子的理由
し	范例	彼は医者にも行かない`し`、薬も飲んでいません。あの人は酒も飲まない`し`、タバコも吸わない`し`、今どき珍しい青年だ。
たり	类型	并列助词
たり	接续	接在`用言`或助动词连用形后。由“たり”构成的联合式词组具有体言的性质，可以像体言一样用，还可以后接“する”像サ变动词词干一样使用，或者可以直接入句做状语
たり	解说	AたりBたりCたり，又A又B又C 表示动作在某一时间内变替进行或状态交替出现 Aたりする，以A为代表进行举例表示举例或者并列，言外暗示还有诸如此类事情。这可以作为并列的特殊用法。
たり	范例	その老人は泣い`たり`騒い`だり`しました。飲ん`だり`食べ`たり`、十分腹をこしらえた。近頃の天気は寒かっ`たり`暑かっ`たり`してたいへん不順です。うそをつい`たり`してはいけません。それぐらいのことで怒っ`たり`するものではない。
ては	类型	连续助词
ては	接续	接在动词、动词型活用助动词、形容词、形容词型活用助动词的连用形后接在名词、形容动词词干、形容动词型活用助动词词干后时用“では”
ては	解说	动词ては动词，A又B、每次A都B 表示`反复出现、进行`的行为动作基本上只会是成对出现，不会有两个以上的动词需要注意在表示`每次・・`这样的情况下，ては看起来非常类似`表示假定条件`的用法，注意区分
ては	范例	彼は非常に本が好きで、町へ行っ`ては`本を四、五冊買ってきます。(`每次`上街都) 町へ行っ`ては`アイスクリームを買って食べる。(`每次`上街都) 雪は消え`ては`降り、降っ`ては`また消えた。

XII. 语法解析范例

| 注解

微信支付接入

Fri, 27 Dec 2019 03:36:22 GMT

1. 前言
2. 支付流程
- - 2.1 网页端
  - 2.2 移动原生
3. 准备工作
4. API & SDK
5. 沙箱使用
6. 错误处理
- 6.1 回调处理
- 6.2 修复订单
7. 上线生效
Appendix
- 链接

1. 前言

微信支付的接入，权当笔记。

2. 支付流程

2.1 网页端

官方文档：扫码支付 > 模式二。

官方配图：

流程涉及到几个角色：

PC网站网页
PC网站后台
微信支付系统

支付流程如下：

用户打开PC网站网页的商品页
用户对商品进行下单
PC网站网页发送下单请求到PC网站后台
PC网站后台在自身系统内生成订单（生成内部订单号），并返回给网页
PC网站网页获得内部订单信息，并将用户导向到支付页面
用户确认订单内容，并开始付款流程
PC网站网页发起支付请求到PC网站后台
PC网站后台向微信支付系统发起下单请求，并将返回的信息交付给PC网站网页
PC网站网页收到微信支付返回信息，将其中的QRCode渲染到页面
用户打开微信，使用扫码的方式完成支付
微信支付系统确认支付完成，向notify_url发送回调信息
PC网站后台验证微信支付回调完成，标记订单状态为已支付

2.2 移动原生

官方文档：APP支付 > 业务流程。

官方配图：

流程涉及到几个角色：

PC网站网页
PC网站后台
微信支付系统

支付流程如下：

用户打开PC网站网页的商品页
用户对商品进行下单
PC网站网页发送下单请求到PC网站后台
PC网站后台在自身系统内生成订单（生成内部订单号），并返回给网页
PC网站网页获得内部订单信息，并将用户导向到支付页面
用户确认订单内容，并开始付款流程
PC网站网页发起支付请求到PC网站后台
PC网站后台向微信支付系统发起下单请求，并将返回的信息交付给PC网站网页
PC网站网页收到微信支付返回信息，使用其中的参数唤起微信APP
用户在微信APP中完成支付
微信支付系统确认支付完成，向notify_url发送回调信息
PC网站后台验证微信支付回调完成，标记订单状态为已支付

3. 准备工作

微信的权限系统非常有问题，没有分级的子账号，只有一个申请人所拥有的主账号。这导致了后续的一系列操作全部都必须主账号持有人来完成（对，你没有看错，必须你的老板来操作，别人不能代劳）。

申请人必须操作：

申请公司账号
申请支付应用

申请完成之后，必须获得以下几个信息，程序才可以对接：

APPID：支付应用的ID
商户号：商户的ID
商户的API秘钥：这里切记是商户秘钥；微信整个生态中应用非常繁多，因此各种秘钥也多，特别是去生成秘钥的又是老板，一般没有技术经验，所以这步非常非常容易出错，会导致后面验证签名无论如何都不正确，所以一定要当心，必须是商户秘钥

微信支付也有证书，但这并不是必须项，大部分支付API是不需要证书的，只有部分才需要。证书也是在商户部分申请，申请完之后可以打包下载，里面含文件：

apiclient_cert.p12：证书pkcs12格式
apiclient_cert.pem：证书
apiclient_key.pem：私钥

申请及配置的相关操作可以看这篇：微信公众号支付配置，以及微信APP支付配置。

移动端还会遇到制作应用签名的问题：Android App 签名生成教程。

4. API & SDK

4.1 SDK选择

npm上可用的SDK包基本上只有：tenpay。

SDK的使用：

const tenpay = require('tenpay');
const config = {
  appid: '公众号ID',
  mchid: '微信商户号',
  partnerKey: '微信支付安全密钥',
  pfx: require('fs').readFileSync('证书文件路径'),
  notify_url: '支付回调网址',
  spbill_create_ip: 'IP地址'
};
// 方式一
const api = new tenpay(config);
// 方式二
const api = tenpay.init(config);
 
// 调试模式(传入第二个参数为true, 可在控制台输出数据)
const api = new tenpay(config, true);
 
// 沙盒模式(用于微信支付验收)
const sandboxAPI = await tenpay.sandbox(config);

config说明:

appid - 公众号ID(必填)
mchid - 微信商户号(必填)
partnerKey - 微信支付安全密钥(必填, 在微信商户管理界面获取)
pfx - 证书文件(选填, 在微信商户管理界面获取)
- 当不需要调用依赖证书的API时可不填此参数
- 若业务流程中使用了依赖证书的API则需要在初始化时传入此参数
notify_url - 支付结果通知回调地址(选填)
- 可以在初始化的时候传入设为默认值, 不传则需在调用相关API时传入
- 调用相关API时传入新值则使用新值
refund_url - 退款结果通知回调地址(选填)
- 可以在初始化的时候传入设为默认值, 不传则使用微信商户后台配置
- 调用相关API时传入新值则使用新值
spbill_create_ip - IP地址(选填)
- 可以在初始化的时候传入设为默认值, 不传则默认值为127.0.0.1
- 调用相关API时传入新值则使用新值

证书相关可以查阅：什么是API证书？如何获取API证书？。

如果在接入的时候遇到签名问题，可以使用：微信支付接口签名校验工具或微信公众平台支付接口调试工具进行调试。

4.2 API使用基础

4.2.1 网页端

API接入手册：扫码支付 > 接口规则 > 协议规则。API列表：扫码支付 > API列表 > 统一下单。

4.2.2 移动原生

API接入手册：APP支付 > 接口规则 > 协议规则。API列表：APP支付 > API列表 > 统一下单。

4.3 常用接口

4.3.1 统一下单接口

范例代码：

const {prepay_id, code_url} = await this.wxpay.unifiedOrder({
    out_trade_no: orderId.toString(),
    body: name,
    // 微信支付的金额是不带小数位的，所有的小数金额都必须*100转为正整数
    // 数值先会被小数点后2位截断或补足，然后转为整数字符串
    // 8.8     => 8.80 => 880
    // 9.24678 => 9.25 => 925
    total_fee: (price).toFixed(2).replace(".", ""),
    trade_type: type, // NATIVE：扫码支付 | APP：原生支付
    product_id: productId,
});

return {
    prepayId: prepay_id,
    codeUrl: code_url,
};

拿到返回值之后，后续根据支付类型不同，处理方式也不一样：

扫码支付
需要将code_url的值，转换为QRCode，后续前端才可以将其渲染到HTML页面上（当然也可以直接将url传给前端，让前端渲染）。这里比较好用的是：qrcode。

后端代码：

const QRCode = require("qrcode");

// ...

const svg = await (QRCode as any).toString(result.codeUrl, {type: "svg"});

HTML页面：

<html>
<head></head>
<body>
  <div id="qrcode" style="width: 200px; height: 200px;"></div>
</body>
</html>

前端代码：

function renderXml(id, xmlString){ // xmlString: svg content
  let doc = new DOMParser().parseFromString(xmlString, "application/xml");
  let el = document.getElementById(id);
  el.appendChild(el.ownerDocument.importNode(doc.documentElement, true));
}

renderXml("qrcode", res.data.extra.codeUrl);

原生支付
在统一下单接口完成之后，还需要根据prepay_id来申请唤起微信的参数：

const params = await this.wxpay.getAppParamsByPrepay({prepay_id: prepayId});

4.3.2 订单查询接口

范例代码：

const order = await this.wxpay.orderQuery({out_trade_no: orderId.toString()});

4.4 金额问题

在刚才4.3.1的例子中，代码里其实已经体现出来了。微信支付的金额和支付宝是不一样的，支付宝的金额就是自然的数额，带小数点后两位。而微信的做法不同，微信要求调用接口下单的时候的支付金额必须不带小数位，所有的金额都是小数点后两位的数字*100转化为整数的数额。也就是说下单接口金额为1的情况，实际支付的是0.01。

// 微信支付的金额是不带小数位的，所有的小数金额都必须*100转为正整数
// 数值先会被小数点后2位截断或补足，然后转为整数字符串
// 8.8     => 8.80 => 880
// 9.24678 => 9.25 => 925
total_fee: (price).toFixed(2).replace(".", "")

4.5 回调处理

微信的所有API都是使用XML作为输入和输出，因此获得的回调信息也是XML。因为之前的API调用中都有SDK处理完了，所以这里就有点恶心，需要自己处理。

回调结构：

export interface IResOrderPayed {
    return_code: string; // SUCCESS
    return_msg: string; // OK
    appid: string; // wx3...
    mch_id: number; // 156..
    nonce_str: string; // cwGl...
    sign: string; // C51A...
    result_code: string; // SUCCESS
    openid: string; // oqvcFj-Uf...
    is_subscribe: string; // N
    trade_type: string; // NATIVE
    bank_type: string; // OTHERS
    total_fee: number; // 1，需要 / 100
    fee_type: string; // CNY
    transaction_id: string; // 42000004...
    out_trade_no: number;
    attach: string; // ""
    time_end: number; // 2019XXXX144155
    trade_state: string; // SUCCESS
    cash_fee: number; // 1，需要 / 100
    trade_state_desc: string; // 支付成功
    cash_fee_type: string; // CNY
}

5. 沙箱使用

微信支付的沙箱和支付宝有点不同，支付宝是完全隔离，从环境、访问地址到账号，支付的支付宝APP全部都是单独分离的。微信则不同，账号、测试用APP都还是原来的微信商户号以及用户真实的微信APP，但访问地址是隔离的，在原来的API地址中间插入/sandboxnew/。

虽然易用性上看起来是微信占优，但实际使用上微信的沙箱有相当多的问题，甚至我研发到最后完成，都完全没使用过沙箱，都是使用0.01的金额进行下单测试。

5.1 沙箱申请

和支付宝一样，微信支付的沙箱使用不需要额外申请。

5.2 沙箱使用

使用方面，可以看一篇第三方的教程：浅析微信支付：如何使用沙箱环境测试。

在使用刚才说的SDK的情况下，只需要在SDK初始化的地方做点调整即可：

const config = {
    appid: vendorConfig.appId,
    mchid: vendorConfig.mchId,
    partnerKey: vendorConfig.appSecret,
    pfx: LibFs.readFileSync(LibPath.join(__dirname, "../../../pem/wxpay/apiclient_key.pem")).toString(),
    notify_url: vendorConfig.callbackUrl,
    spbill_create_ip: vendorConfig.allowedIp,
} as Tenpay.IConfig;

// wxpay
if (isSandbox) {
    tenpay.init(config, isTest).getSignkey().then((res) => {
        const key = res.sandbox_signkey;
        this.wxpay = tenpay.init(Object.assign(config, {partnerKey: key, sandbox: true}), isTest);
    }).catch((err) => {
        throw err;
    });
} else {
    this.wxpay = tenpay.init(config, isTest);
}

沙箱每次使用的秘钥（商户的API秘钥）和正式环境不一样，正式环境是配置死的，直接拿下来用即可。而沙箱则需要先使用正式环境的商户秘钥去调用getSignkey获取沙箱使用的临时商户秘钥，才可以后续继续调用API。

5.3 沙箱问题

理解了沙箱的隔离以及如何初始化沙箱SDK之后，如果直接实际调用的话，还是会遇到问题：

参见：微信支付的沙箱环境能否使用？#668。

这里还需要额外做一个操作：在微信支付商户接入验收助手这个公众号申请你的验收case，写入验收金额作为use case。后续在沙箱环境做测试的时候，金额必须完全符合之前申请的验收case，否则报错。

6. 错误处理

6.1 回调处理

try {
    // 业务处理
    
    ctx.type = "application/xml";
    ctx.body = "" +
`<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
</xml>`;
} catch (err) {
    console.log(err);
    ctx.type = "application/xml";
    ctx.body = "" +
`<xml>
<return_code><![CDATA[FAIL]]></return_code>
<return_msg><![CDATA[${err.message}]]></return_msg>
</xml>`;
}

6.2 修复订单

在某些情况下，回调可能没有收到，或者一直报错导致回调没有正常处理。表现在用户视角，就是支付完成后订单状态无法正常改为支付完成（也就不会发货）。这是很糟糕的，因此需要制作修复订单功能。

客户端在检查到订单状态为等待支付之后，可以提供一个入口给用户，用户点击之后，应用后端应该向支付宝查询订单信息，如果在支付宝这里已经是已支付而在应用这边还是等待支付的话，就立即将业务订单改为已支付，并向用户发货。

7. 上线生效

微信支付应该是在应用申请审核通过的时候就直接上线了，不需要额外操作。

Appendix

链接

支付宝接入

Fri, 27 Dec 2019 02:36:22 GMT

1. 前言
2. 支付流程
- - 2.1 网页端
  - 2.2 移动原生
3. 准备工作
4. API & SDK
5. 沙箱使用
6. 错误处理
- 6.1 回调处理
- 6.2 修复订单
7. 上线生效
Appendix
- 链接

1. 前言

支付宝的接入，权当笔记。

2. 支付流程

2.1 网页端

PC网页端的支付，官方文档在：开发文档 / 电脑网站支付 / 快速接入。这篇应该说是完整的tutorial，里面也包含了支付的整个流程。

官方配图：

总觉得支付宝的这个流程图有点问题，并没有很好解释流程顺序。这里整理一个文字版。

流程涉及到几个角色：

PC网站网页
PC网站后台
支付宝系统

支付流程如下：

用户打开PC网站网页的商品页
用户对商品进行下单
PC网站网页发送下单请求到PC网站后台
PC网站后台在自身系统内生成订单（生成内部订单号），并返回给网页
PC网站网页获得内部订单信息，并将用户导向到支付页面
用户确认订单内容，并开始付款流程
PC网站网页发起支付请求到PC网站后台
PC网站后台向支付宝系统发起下单请求
- 其中附加了notify_url，会在支付完成后收到回调
- 且附加了return_url，会在支付完成后将页面导向到该页面
PC网站后台将支付宝返回的信息交付给PC网站网页
PC网站网页收到支付宝返回信息，使用其中的信息将页面导向到支付宝的付款页面
用户在支付宝的付款页面完成付款
支付宝系统确认支付完成，将用户网页重定向到return_url的页面
支付宝系统确认支付完成，向notify_url发送回调信息
PC网站后台验证支付宝回调完成，标记订单状态为已支付

2.2 移动原生

移动端原生支付和PC网页支付差异不是很大，官方文档在：开发文档 / App支付 / 快速接入。

官方配图：

这个图还算可以，老样子整理一个文字版。

流程涉及到几个角色：

手机APP
APP后台
支付宝系统

支付流程如下：

用户打开手机APP的商品页
用户对商品进行下单
手机APP发送下单请求到APP后台
APP后台在自身系统内生成订单（生成内部订单号），并返回给APP
手机APP获得内部订单信息，并将用户导向到支付页面
用户确认订单内容，并开始付款流程
手机APP发起支付请求到APP后台
APP后台向支付宝系统发起下单请求，获得支付宝APP唤醒参数，并交付给手机APP
- 其中附加了notify_url，会在支付完成后收到回调
手机APP收到支付宝返回信息，使用其中的参数唤醒支付宝APP
用户在支付宝APP完成付款
支付宝系统确认支付完成，返回手机APP
支付宝系统确认支付完成，向notify_url发送回调信息
APP后台验证支付宝回调完成，标记订单状态为已支付

3. 准备工作

在正式接入支付宝之前，还需要做一些准备工作，主要是一系列账号、应用、秘钥的申请。

3.1 账号申请

公司账号申请都是老板做的事情，虽然繁琐但和技术人员没什么关系。创建完成后可以通过账户成员管理将员工账号加入到管理群组里，方便员工直接进行开发。

员工可以通过这个链接，登入到支付宝进行账号和应用的管理。

3.2 应用申请

见官方文档：开发文档 / 开发指南 / 创建应用。

刚创建出来的应用是没有任何功能的，支付宝的各种功能（包括最基础的支付功能）都是支付应用下的应用功能，一般来说每个都需要单独开通，某些开通还需要一定的条件，比如说网页支付开通的话你必须首先要有一个已经上线的网页而且要有明确的支付功能（申请失败如下）。等等。见：签约功能。

在这一步最重要的是要把支付应用的APP_ID记录下来。

3.3 秘钥申请

见官方文档：开发文档 / 签名专区 / 第一步：生成 RSA 密钥。

官方有提供一个工具支付宝开放平台开发助手，可以用这个工具进行秘钥制作，比较方便：

后续研发上遇到签名问题可以参考：自助排查以及常见问题。

这一步操作完成后应该会获得三个文件，需要妥善保存：

alipay的公钥
- 文件以-----BEGIN PUBLIC KEY-----开头
- 文件以-----END PUBLIC KEY-----结尾
应用的公钥
- 文件以-----BEGIN PUBLIC KEY-----开头
- 文件以-----END PUBLIC KEY-----结尾
应用的私钥
- 文件以-----BEGIN RSA PRIVATE KEY-----开头
- 文件以-----END RSA PRIVATE KEY-----结尾

下载下来的公钥和私钥都是不断行的连续字符串，还需要借助像是Online tool to format private key. - SAMLTool.com这样的工具进行格式转换，断行。如果没有文件头和文件尾的话，还需要手动添加。

4. API & SDK

4.1 SDK选择

Node.js进行开发的话，有两个npm库可选：

alipay-node-sdk：这个库非官方，但维护的很好，而且使用的人也不少，可以一用
Alipay SDK：这个库是官方的，但封装得还没有上一个好，而且文档也很糟糕，但毕竟是官方的，所以还是首选

官方SDK的使用需要了解：

SDK 配置
包含业务参数
不包含业务参数
页面类接口调用：其实后续PC和APP下单用的都是这种模式，调用支付宝接口后获得对应的信息，然后返回给应用客户端，让它们触发后续流程
通知验签

此外，官方SDK有一个比较严重的BUG：设置了 passbackParams 会导致 alipaySdk.checkNotifySign 失败 #45，会直接影响使用，需要注意。

解决方案：

payload.passback_params = encodeURIComponent(payload.passback_params)
const verified = alipaySdk.checkNotifySign(payload)

4.2 API使用基础

官方的API文档在：支付API。

支付宝的API的接口，参数都分为公共请求参数以及请求参数。简单点来说：

公共请求参数：支付宝级别比较顶层的参数，比如说：app_id、sign等
请求参数：非公共请求参数之外的其他一切参数

请求参数会放在公共请求参数的biz_content里，至于怎么放进去的可以不用关心，SDK都会直接封装掉。

API的测试可以通过：在线调试(Beta)来模拟使用。

4.3 常用接口

官方SDK的初始化，沙箱和正式用的是两套秘钥，这块需要动态处理下：

import AlipaySdk from "alipay-sdk/lib/alipay";
import AlipayFormData from "alipay-sdk/lib/form";

// ...

const vendorConfig = Config.get().getVendor(Constant.VENDOR_ALIPAY_ID) as IVendorConfigAlipay;

const isSandbox = Config.get().getRaw().sandbox;

this.notifyUrl = vendorConfig.callbackUrl;
this.returnUrl = vendorConfig.returnUrl;

const pubKeyPath = LibPath.join(
    __dirname, "../../../pem/alipay", isSandbox ? "sandbox/alipay.pub.txt" : "alipay.pub.txt",
);
const priKeyPath = LibPath.join(
    __dirname, "../../../pem/alipay", isSandbox ? "sandbox/app.pri.txt" : "app.pri.txt",
);
this.gateway = isSandbox
    ? "https://openapi.alipaydev.com/gateway.do"
    : "https://openapi.alipay.com/gateway.do";
console.log("alipay::sdk::pubKeyPath", pubKeyPath);
console.log("alipay::sdk::priKeyPath", priKeyPath);
console.log("alipay::sdk::gateway", this.gateway);

this.aliPay = new AlipaySdk({
    appId: vendorConfig.appId,
    alipayPublicKey: LibFs.readFileSync(pubKeyPath).toString(),
    privateKey: LibFs.readFileSync(priKeyPath).toString(),
    gateway: this.gateway,
    signType: "RSA2",
});

4.3.1 PC网页支付下单

文档在：alipay.trade.page.pay。

范例代码：

const formData = new AlipayFormData();
formData.addField("returnUrl", this.returnUrl);
formData.addField("notifyUrl", this.notifyUrl);
formData.addField("bizContent", {
    outTradeNo: orderId.toString(),
    productCode: "FAST_INSTANT_TRADE_PAY",
    totalAmount: price,
    subject: name,
    body: desc,
    passbackParams: encodeURIComponent(JSON.stringify({}})),
    timeoutExpress: `${Math.floor(seconds / 60)}m`,
    qrPayMode: 0,
});

return await this.aliPay.exec(
    "alipay.trade.page.pay",
    {},
    {formData, log: {info: console.log, error: console.log}},
);

范例返回：

<form action="https://openapi.alipaydev.com/gateway.do?method=alipay.trade.page.pay&app_id=...&charset=utf-8&version=1.0&sign_type=RSA2&timestamp=2019-XX-XX%2015%3A20%3A24&return_url=...&notify_url=...&sign=..." method="post" name="alipaySDKSubmit1577431224474" id="alipaySDKSubmit1577431224474">
  <input type="hidden" name="alipay_sdk" value="alipay-sdk-nodejs-3.0.8" /><input type="hidden" name="biz_content" value="{&quot;out_trade_no&quot;:143123,&quot;product_code&quot;:&quot;FAST_INSTANT_TRADE_PAY...}" />
</form>
<script>document.forms["alipaySDKSubmit1577431224474"].submit();</script>

返回的是一个字符串，这串字符串交付给网页，让JS直接append到当前页面上，就会进行跳转（form.submit），到支付宝的页面让用户付款。

4.3.2 APP支付下单

文档在：alipay.trade.app.pay。

范例代码：

const formData = new AlipayFormData();
formData.setMethod("get");
formData.addField("notifyUrl", this.notifyUrl);
formData.addField("bizContent", {
    outTradeNo: orderId.toString(),
    productCode: "QUICK_MSECURITY_PAY",
    totalAmount: price.toString(),
    subject: name,
    body: desc,
    passbackParams: encodeURIComponent(JSON.stringify({}})),
    timeoutExpress: `${Math.floor(seconds / 60)}m`,
});

return await this.aliPay.exec(
    "alipay.trade.app.pay",
    {},
    {formData, log: {info: console.log, error: console.log}},
) as string;

范例返回：

https://openapi.alipaydev.com/gateway.do?method=alipay.trade.app.pay&app_id=...&charset=utf-8&version=1.0&sign_type=RSA2&timestamp=2019-XX-XX%2015%3A23%3A25&notify_url=...

这一串字符串需要去掉头部的gateway：https://openapi.alipaydev.com/gateway.do?，只需要把剩下的参数部分交付给移动APP即可，移动APP会使用这些参数唤醒支付宝APP。

4.3.3 支付宝订单查询

文档在：alipay.trade.query。

范例代码：

return await this.aliPay.exec("alipay.trade.query", {
    bizContent: {out_trade_no: orderId.toString()},
}, {log: {info: console.log, error: console.log}}) as any;

返回的结果详见官方API文档。

4.4 回调处理

4.4.1 return_url

在return_url上收到的参数如下：

{
    "charset": "utf-8",
    "out_trade_no": "143123",
    "method": "alipay.trade.page.pay.return",
    "total_amount": "0.01",
    "sign": "B5wBu/icxG9u12XyBKUu...",
    "auth_app_id": "201...422",
    "version": "1.0",
    "app_id": "201...422",
    "sign_type": "RSA2",
    "seller_id": "208...342",
    "timestamp": "2019-XX-XX 15:48:17"
}

4.4.2 notify_url

在notify_url上收到的参数如下：

{ 
  "gmt_create": "2019-XX-XX 15:48:01",
  "charset": "utf-8",
  "subject": "测试商品名",
  "sign": "OMcW3K9Sy...",
  "buyer_id": "208...342",
  "body": "测试商品描述",
  "invoice_amount": "0.01",
  "notify_id": "2019...589",
  "fund_bill_list": "[{\"amount\":\"0.01\",\"fundChannel\":\"ALIPAYACCOUNT\"}]",
  "notify_type": "trade_status_sync",
  "trade_status": "TRADE_SUCCESS",
  "receipt_amount": "0.01",
  "app_id": "201...422",
  "buyer_pay_amount": "0.01",
  "sign_type": "RSA2",
  "seller_id": "208...342",
  "gmt_payment": "2019-XX-XX 15:48:15",
  "notify_time": "2019-XX-XX 15:48:16",
  "passback_params": "%7B%22orderId%22%3A143123%2C%22salt%22%3A%221fvwtia2k4nuszx2%22%7D",
  "version": "1.0",
  "out_trade_no": "143123",
  "total_amount": "0.01",
  "trade_no": "2019...383",
  "auth_app_id": "201...422",
  "point_amount": "0.00"
}

5. 沙箱使用

官方文档在：开发文档 / 开发指南 / 使用沙箱环境。移动APP的沙箱使用还需要一些额外的调整：开发文档 / App支付 / 沙箱联调指南。

5.1 沙箱申请

沙箱不需要额外申请，在支付应用创建完成之后，其沙箱自动创建完成。

5.2 沙箱管理

沙箱有单独的管理页面，上面主要要处理几个事情：

获取沙箱的APP ID；沙箱应用是单独的应用，和正式应用是隔离的，在沙箱环境使用正式应用的APP ID会告知没有该应用，反之亦然
制作沙箱单独的秘钥；该秘钥和正式环境是隔离的，需要单独制作
获取沙箱支付宝APP的账号和密码以及支付密码；在测试的时候会使用到

5.3 沙箱支付

沙箱环境有单独的一个调试用支付宝APP（用正常的支付宝APP扫码会失败，也无法被沙箱应用唤醒），只有android版本：下载链接。

在沙箱管理页面上能获取到对应的账号信息等。使用这些信息登入支付宝沙箱APP，然后就可以进行测试支付了。

6. 错误处理

6.1 回调处理

无论对错，业务服务器后端都需要以text/plain的格式响应，如果回调处理没有问题，就返回success，如果报错，则返回fail。

try {
    // 在这里处理业务

    ctx.type = "text/plain";
    ctx.body = "success";
} catch (err) {
    console.log(err);
    ctx.type = "text/plain";
    ctx.body = "fail";
}

6.2 修复订单

7. 上线生效

开发完成（甚至在这之前）就可以上线应用，之前在申请应用的时候提到过的功能开通，签约等，很大一部分都需要应用上线之后才可以做，所以这个操作可以尽早。最基础的支付功能基本上签约没什么难度，早点签约早点开通。

Appendix

链接

Docker Registry 的简单使用

Thu, 26 Dec 2019 03:36:22 GMT

1. 前言
2. 安装 & 启动
3. 访问限制
3. API
4. 删除镜像

1. 前言

Docker和镜像在工作中是越来越常见了，而镜像仓库的需求也变得越来越常见。Docker官方给的解决方案是私有Registry仓库，官方也给了镜像进行对应的使用。但不得不说Docker的Registry是真的不好用：

没有UI界面
只有很弱的访问权限限制
所有接口都必须通过HTTP请求方式进行，没有提供命令行工具等简化操作
没有删除镜像的手段

此外还有很多，这里就不一并列举了。

因此，市面上也有不少alternative替代方案，做的最好的应该是harbor。如果是大型企业或者是有比较严谨的权限控制需求的话，推荐使用harbor。

但针对小公司来说，更简单快速的部署和更简单的运维是相对来说更重要的事情，因此Docker Registry的使用也是有市场的。这里就简单做下使用上的介绍。

2. 安装 & 启动

使用的还是官方的镜像：registry。

官方文档在：Deploy a registry server。

启动命令：

$ docker network create registry

$ docker run -d \
    --name docker_registry \
    --network registry \
    --restart=always \
    -p 15000:5000 \
    -v /tmp/registry/auth:/data/registry/auth \
    -v /tmp/registry/data:/var/lib/registry \
    -v /tmp/registry/config.yml:/etc/docker/registry/config.yml \
    -e REGISTRY_AUTH=htpasswd \
    -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
    -e REGISTRY_AUTH_HTPASSWD_PATH=/data/registry/auth/htpasswd \
    registry:2.7.1

容器内配置文件的位置：/etc/docker/registry/config.yml。

当前例子中使用的是没有前置proxy，并且仅设置了最简单的用户名密码访问限制的情况。关于这块的访问限制相关，更详细的内容可以查看官方文档：Restricting access。

生成秘钥可以使用命令：

$ docker run --rm \
    --entrypoint htpasswd \
    registry:2.7.1 \
    -Bbn username password > /tmp/registry/auth/htpasswd

如果需要结合nginx使用的话（一般推荐这样做），需要参见：Authenticate proxy with nginx。

参考配置文件：

events {
    worker_connections  1024;
}

http {

  upstream docker-registry {
    server registry:5000;
  }

  ## Set a variable to help us decide if we need to add the
  ## 'Docker-Distribution-Api-Version' header.
  ## The registry always sets this header.
  ## In the case of nginx performing auth, the header is unset
  ## since nginx is auth-ing before proxying.
  map $upstream_http_docker_distribution_api_version $docker_distribution_api_version {
    '' 'registry/2.0';
  }

  server {
    listen 443 ssl;
    server_name myregistrydomain.com;

    # SSL
    ssl_certificate /etc/nginx/conf.d/domain.crt;
    ssl_certificate_key /etc/nginx/conf.d/domain.key;

    # Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
    ssl_protocols TLSv1.1 TLSv1.2;
    ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    # disable any limits to avoid HTTP 413 for large image uploads
    client_max_body_size 0;

    # required to avoid HTTP 411: see Issue #1486 (https://github.com/moby/moby/issues/1486)
    chunked_transfer_encoding on;

    location /v2/ {
      # Do not allow connections from docker 1.5 and earlier
      # docker pre-1.6.0 did not properly set the user agent on ping, catch "Go *" user agents
      if ($http_user_agent ~ "^(docker\/1\.(3|4|5(?!\.[0-9]-dev))|Go ).*$" ) {
        return 404;
      }

      # To add basic authentication to v2 use auth_basic setting.
      auth_basic "Registry realm";
      auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;

      ## If $docker_distribution_api_version is empty, the header is not added.
      ## See the map directive above where this variable is defined.
      add_header 'Docker-Distribution-Api-Version' $docker_distribution_api_version always;

      proxy_pass                          http://docker-registry;
      proxy_set_header  Host              $http_host;   # required for docker client's sake
      proxy_set_header  X-Real-IP         $remote_addr; # pass on real client's IP
      proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header  X-Forwarded-Proto $scheme;
      proxy_read_timeout                  900;
    }
  }
}

3. 访问限制

在刚才的启动命令部分已经提到了如何制作用户名和密码的访问限制秘钥。而作为用户访问Registry则是另一回事。

私有Registry如果架设的是HTTP，而不是HTTPS的话，访问的客户端需要修改配置，将该Registry的地址列入允许的不安全访问列表内，才可以正常访问。一般来说这个配置文件是在：~/.docker/daemon.json。

范例：

{
  "insecure-registries" : [
    "127.0.0.1:15000"
  ]
}

修改完成之后必须重启本地的docker进程，该配置才会生效。

然后使用docker login 127.0.0.1:15000进行登录，这会在~/.docker/config.json文件中生成一个登录项。但访问凭证一般不会直接存储在这里，OSX操作系统是使用keychain来进行存储。参见：Credentials store。

在某些场合，需求预先生成访问凭证，而不是到实际运行的主机上进行docker login。这时候使用命令来生成凭证，并手动生成对应的登录项配置文件，放到指定的位置来生效。

根据用户名和密码来生成凭证：

$ echo -n "$username:$password" | base64
# dGVzdDphYmMxMjNf

生成登录项配置文件~/.docker/config.json：

{
    "auths": {
        "127.0.0.1:15000": {
            "auth": "dGVzdDphYmMxMjNf"
        }
    }
}

这样后续的使用就没有问题了，当然这样做是非常不安全的，不推荐使用。

3. API

因为registry没有提供UI界面，所有的操作都必须通过RESTful API来进行。

官方文档在：HTTP API V2。

常用API范例：

查看所有的仓库清单

$ curl -u $username:$password http://127.0.0.1:15000/v2/_catalog | jq .

结果：

{
  "repositories": [
    "fullstack/builder",
    "fullstack/common",
    "fullstack/gateway",
    "fullstack/runner",
    "fullstack/server"
  ]
}

查看某个仓库的所有tag

$ curl -u $username:$password http://127.0.0.1:15000/v2/fullstack/common/tags/list | jq .

结果：

{
  "name": "fullstack/common",
  "tags": [
    "0.0.42",
    "0.0.43",
    "0.0.35",
    "0.0.32",
    "0.0.33",
    "0.0.34"
  ]
}

查看某个仓库某个tag的digest

$ curl -u $username:$password http://127.0.0.1:15000/v2/fullstack/common/manifests/0.0.43 \
    --header "Accept: application/vnd.docker.distribution.manifest.v2+json" | jq '.config|.digest'

结果：

"sha256:23ffb64a5f8c7bf748eb80830d7f3be7f5de613ba9d37817fe7771180b59fdc5"

根据digest删除某个仓库的某个tag

$ curl $username:$password -I -X DELETE "http://127.0.0.1:15000/v2/fullstack/common/manifests/sha256:23ffb64a5f8c7bf748eb80830d7f3be7f5de613ba9d37817fe7771180b59fdc5"

结果：

HTTP/1.1 202 Accepted
Docker-Distribution-Api-Version: registry/2.0
X-Content-Type-Options: nosniff
Date: Thu, 26 Dec 2019 09:17:51 GMT
Content-Length: 0

只要返回的CODE是202，说明就是没问题的，正常删除。

4. 删除镜像

刚才在API中已经提到了根据digest删除某个tag，但是这时候镜像的真实数据还并没有被删除。还需要做几步操作。

首先需要修改Registry的配置文件，允许删除操作。注意下面范例的：storage.delete.enabled: true。

version: 0.1
log:
  fields:
    service: registry
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3

然后需要进入容器内部进行删除操作：

$ docker exec -it /bin/sh
/# /bin/registry garbage-collect /etc/docker/registry/config.yml

即便这样，被删除的tag仍旧会出现在tag列表API的结果里。Docker官方对删除就完全没做好支持。

Gitea简单介绍及使用

Thu, 26 Dec 2019 02:36:22 GMT

1. 前言
2. 使用

1. 前言

Gitea是一款使用Golang编写的可自运营的代码管理工具。

在这个领域，名气最响的应该是Gitlab。但实际使用中Gitlab也有点问题，首先就是资源占用。Gitlab是使用ruby编写的，好几年之前刚出来的时候，一台1G内存的虚拟主机连安装运行都做不到，着实震惊。时至今日都已经发展到了以docker镜像分发，gitlab仍旧会有体积和运行时资源占用的问题。另一点就是功能，对于一般标准团队来说，gitlab的功能太过于丰富，这是往好的地方说，往坏的地方说就是它包含了太多不需要的东西，而这些东西还占用磁盘和运行时资源。

于是着手查看开源的alternative方案，很快就找到了golang研发的gitea。使用golang研发的软件分发都很容易，体积小，安装使用简单，运行时占用资源少。且gitea的功能很完备，某些自身不具备的功能也能通过第三方来解决，比如CI就可以结合同样是golang研发的drone来实施。

2. 使用

2.1 安装启动

安装使用仍旧推荐使用官方镜像：gitea/gitea。官方指引：从Docker安装。

  localbuild_gitea:
    image: gitea/gitea:1.10.0
    container_name: localbuild_gitea
    hostname: localbuild_gitea
    networks:
      - net
    ports:
      - 13000:13000
      - 122:122
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:13000 -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - ./vendor/gitea:/data

关于启动时的环境变量相关，官方有一个讨论帖：Configure with env variables #350，但貌似还没有任何结论，当前最佳实践是做好配置文件之后映射到容器内。

关于gitea使用的数据库，如果是默认配置的话，是会使用Postgre数据库，存放在容器内的/data/gitea/gitea.db位置。

gitea的数据全部都放在容器内的/data文件夹下，一般需要将这个文件夹映射出来。

/data文件夹内部文件结构如下：

/-
 | git /-                                           # 存放所有git仓库数据
 |      | repositories /-                           # 代码库存放位置
 |      |               | fullstack /-              # 组织
 |      |               |            | common.git   # 组织下的代码库
 |      |               |            | gateway.git
 |      |               |            | server.git
 | gitea /-                                         # 存放gitea自身的系统文件
 |        | conf /-
 |        |       | app.ini                         # gitea配置文件
 |        | log                                     # gitea日志文件
 |        | gitea.db                                # Postgre数据库文件
 | ssh                                              # 秘钥文件

2.2 配置

官方文档在：配置说明。

映射路径在容器内的/data/gitea/conf/app.ini。一般主要是URL和端口之类的需要调整下，还有就是数据库的访问方式。

2.3 Command Line

gitea还可以作为一个命令行工具来执行CLI命令，官方文档在：Command Line。执行的时候可能还会需要用到部分环境变量，见：环境变量清单。

不过作为命令行工具来使用的机会比较少见。

2.4 API

gitea提供RESTful的API，这块是自动化的主力，需要好好看下如何使用。

官方API文档在：Gitea API 使用指南。这篇指引主要是阐明了如何使用API，如何处理访问控制之类的。具体的API调用参数和返回值，以及API列表，可以查看官方的swagger：Gitea API.。

给几个curl调用的例子：

在fullstack组织下，创建代码库common

$ curl -X POST "http://127.0.0.1:13000/api/v1/admin/users/fullstack/repos" \
    -H "accept: application/json" \
    -H "Authorization: token 752e305de4936a769d2ed962b3e019f8866e510a" \
    -H "Content-Type: application/json" -d "{ \"name\": \"common\", \"auto_init\": false, \"private\": true }"

删除fullstack组织下的代码库common

$ curl -X DELETE "http://127.0.0.1:13000/api/v1/repos/fullstack/common" \
    -H "accept: application/json" \
    -H "Authorization: token 752e305de4936a769d2ed962b3e019f8866e510a"

2.5 访问授权

授权主要有两种方式。

2.5.1 Token授权

Token授权是最简单的。通过发行token，让拥有token的终端可以直接调用API进行操作。

发行Token也很简单：

点击右上角用户头像
点击下拉菜单的设置
点击新页面导航栏中间的应用
在管理Access Tokens部分输入Token名，点击生成令牌

需要注意的是，令牌生成之后内容只会展现一次，后续就只有删除操作。如果遗忘的话就只能删除然后申请新的了。

2.5.2 OAuth2授权

OAuth2也算是现在比较常见的授权方法，和Token不同的是两者的应用场景：

Token：更多的用在自动化部署等，需要简单访问权限的场景
OAuth2：更多的用在第三方应用程序和gitea的整合，比如CI工具等

操作上也很简单，在Token同一界面上的管理 OAuth2 应用程序界面部分，按提示操作即可。一样的，秘钥只会在创建完成后展示一次，后续秘钥只能重置，不能再次展示。

Consul Notes

Wed, 25 Dec 2019 02:36:22 GMT

1. 前言
2. 选型
3. 架构
4. 使用
Appendix

1. 前言

Consul一般用来作为服务注册和服务发现软件。官方介绍如下：

文档资料：

2. 选型

市面上常用的开源服务发现软件主要有：consul、etcd、zookeeper。前两者都是用golang研发的，而zookeeper则是java研发的（你懂我意思吧）。

这里就有选型的问题了，不过了解下来相互之间的差异不能说很大，基本上都在可接受范围内。特别是consul和etcd都使用raft作为分布式一致性协议，可以说非常趋同了。etcd关注度更高（特别是K8S官方使用了它），功能简单，主要在大型系统中作为分布式K/V存储使用；而consul的功能更强大（完整、开箱即用）且易用性更高。

3. 架构

官方的架构介绍在：Consul Architecture。

简单来说：

节点分为client和server
server负责存储数据，并形成集群，使用raft保证集群一致性
client负责直接和业务对象连接，并将数据同步到server上
所有的节点都是通过gossip连接起来的

4. 使用

4.1 启动

一般直接使用docker镜像：consul。

启动方面非常简单，全部都是用agent命令，参数细节放在后面的附录部分，太长了：consul agent —help。

常用参数：

--node=$name指定节点名称
--server表示节点是server节点
--bootstrap表示节点以bootstrap模式启动
--ui表示当前节点会提供管理UI界面
--client=0.0.0.0指定监听地址
--join=$host指定启动时尝试加入集群时连接的目标节点

下面给个例子，集群3个server节点，2个client节点：

  fullstack_consul_server1:
    image: consul:1.6.1
    container_name: fullstack_consul_server1
    hostname: fullstack_consul_server1
    networks:
      - net
    ports:
      - 18500:8500
    expose:
      - 8600 # DNS
      - 8500 # HTTP API
      - 8501 # HTTPS API
      - 8502 # gRPC API
      - 8301 # LAN Serf
      - 8302 # Wan Serf
      - 8300 # Server RPC address
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:8500/v1/health/node/consul-server1 -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - consul_server1_data:/consul/data
    environment:
      - CONSUL_BIND_INTERFACE=eth0
    command: [
      agent,
      --node=consul-server1,
      --server,
      --bootstrap,
      --client=0.0.0.0,
      --ui
    ]
  fullstack_consul_server2:
    image: consul:1.6.1
    container_name: fullstack_consul_server2
    hostname: fullstack_consul_server2
    networks:
      - net
    expose:
      - 8600 # DNS
      - 8500 # HTTP API
      - 8501 # HTTPS API
      - 8502 # gRPC API
      - 8301 # LAN Serf
      - 8302 # Wan Serf
      - 8300 # Server RPC address
    depends_on:
      fullstack_consul_server1:
        condition: service_healthy
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:8500/v1/health/node/consul-server2 -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - consul_server2_data:/consul/data
    environment:
      - CONSUL_BIND_INTERFACE=eth0
    command: [
      agent,
      --node=consul-server2,
      --server,
      --client=0.0.0.0,
      --join=fullstack_consul_server1
    ]
  fullstack_consul_server3:
    image: consul:1.6.1
    container_name: fullstack_consul_server3
    hostname: fullstack_consul_server3
    networks:
      - net
    expose:
      - 8600 # DNS
      - 8500 # HTTP API
      - 8501 # HTTPS API
      - 8502 # gRPC API
      - 8301 # LAN Serf
      - 8302 # Wan Serf
      - 8300 # Server RPC address
    depends_on:
      fullstack_consul_server1:
        condition: service_healthy
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:8500/v1/health/node/consul-server3 -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - consul_server3_data:/consul/data
    environment:
      - CONSUL_BIND_INTERFACE=eth0
    command: [
      agent,
      --node=consul-server3,
      --server,
      --client=0.0.0.0,
      --join=fullstack_consul_server1
    ]
  fullstack_consul_client1:
    image: consul:1.6.1
    container_name: fullstack_consul_client1
    hostname: fullstack_consul_client1
    networks:
      - net
    expose:
      - 8600 # DNS
      - 8500 # HTTP API
      - 8501 # HTTPS API
      - 8502 # gRPC API
      - 8301 # LAN Serf
      - 8302 # Wan Serf
      - 8300 # Server RPC address
    depends_on:
      fullstack_consul_server1:
        condition: service_healthy
      fullstack_consul_server2:
        condition: service_healthy
      fullstack_consul_server3:
        condition: service_healthy
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:8500/v1/health/node/consul-client -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - consul_client1_data:/consul/data
    environment:
      - CONSUL_BIND_INTERFACE=eth0
    command: [
      agent,
      --node=consul-client1,
      --client=0.0.0.0,
      --join=fullstack_consul_server1
    ]
  fullstack_consul_client2:
    image: consul:1.6.1
    container_name: fullstack_consul_client2
    hostname: fullstack_consul_client2
    networks:
      - net
    expose:
      - 8600 # DNS
      - 8500 # HTTP API
      - 8501 # HTTPS API
      - 8502 # gRPC API
      - 8301 # LAN Serf
      - 8302 # Wan Serf
      - 8300 # Server RPC address
    depends_on:
      fullstack_consul_server1:
        condition: service_healthy
      fullstack_consul_server2:
        condition: service_healthy
      fullstack_consul_server3:
        condition: service_healthy
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    healthcheck:
      test: wget http://127.0.0.1:8500/v1/health/node/consul-client -q -O - > /dev/null 2>&1
      interval: 10s
      timeout: 20s
      retries: 10
    volumes:
      - consul_client2_data:/consul/data
    environment:
      - CONSUL_BIND_INTERFACE=eth0
    command: [
      agent,
      --node=consul-client2,
      --client=0.0.0.0,
      --join=fullstack_consul_server1
    ]

部署完成后节点如下：

4.2 API

官方API文档在：API Introduction。Consul使用RESTful的HTTP请求来提供服务，所有的客户端或命令行工具无非就是RESTful API的封装。所以如果有需要，可以直接使用curl来发送HTTP请求调用接口。

下面的例子中会涉及到一些demo应用程序的节点：

app server 3个节点
app gateway 3个节点

client1连接了：

client2连接了：

4.2.1 根据节点健康状态获取节点

文档：List Checks in State

这个接口可以有效过滤掉已经失效的节点。

$ curl http://127.0.0.1:18500/v1/health/state/any | jq .

结果：

[
  {
    "Node": "consul-client1",
    "CheckID": "serfHealth",
    "Name": "Serf Health Status",
    "Status": "passing",
    "Notes": "",
    "Output": "Agent alive and reachable",
    "ServiceID": "",
    "ServiceName": "",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 15,
    "ModifyIndex": 15
  },
  {
    "Node": "consul-client1",
    "CheckID": "service:1fw20gk4kq30tk",
    "Name": "Service 'server' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_server2:50052/health: 200 OK Output: OK",
    "ServiceID": "1fw20gk4kq30tk",
    "ServiceName": "server",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 26,
    "ModifyIndex": 29
  },
  {
    "Node": "consul-client1",
    "CheckID": "service:1fw20gk4kq35py",
    "Name": "Service 'gateway' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_gateway3:3000/health: 200 OK Output: OK",
    "ServiceID": "1fw20gk4kq35py",
    "ServiceName": "gateway",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 30,
    "ModifyIndex": 32
  },
  {
    "Node": "consul-client1",
    "CheckID": "service:1fw20hk4kq5i2h",
    "Name": "Service 'gateway' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_gateway1:3000/health: 200 OK Output: OK",
    "ServiceID": "1fw20hk4kq5i2h",
    "ServiceName": "gateway",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 48,
    "ModifyIndex": 49
  },
  {
    "Node": "consul-client2",
    "CheckID": "serfHealth",
    "Name": "Serf Health Status",
    "Status": "passing",
    "Notes": "",
    "Output": "Agent alive and reachable",
    "ServiceID": "",
    "ServiceName": "",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 13,
    "ModifyIndex": 13
  },
  {
    "Node": "consul-client2",
    "CheckID": "service:1fw20hk4kq30n8",
    "Name": "Service 'server' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_server3:50052/health: 200 OK Output: OK",
    "ServiceID": "1fw20hk4kq30n8",
    "ServiceName": "server",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 24,
    "ModifyIndex": 27
  },
  {
    "Node": "consul-client2",
    "CheckID": "service:1fw20ik4kq35th",
    "Name": "Service 'gateway' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_gateway2:3000/health: 200 OK Output: OK",
    "ServiceID": "1fw20ik4kq35th",
    "ServiceName": "gateway",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 31,
    "ModifyIndex": 34
  },
  {
    "Node": "consul-client2",
    "CheckID": "service:eewk9hk4kq2uvy",
    "Name": "Service 'server' check",
    "Status": "passing",
    "Notes": "",
    "Output": "HTTP GET http://fullstack_server1:50052/health: 200 OK Output: OK",
    "ServiceID": "eewk9hk4kq2uvy",
    "ServiceName": "server",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 22,
    "ModifyIndex": 23
  },
  {
    "Node": "consul-server1",
    "CheckID": "serfHealth",
    "Name": "Serf Health Status",
    "Status": "passing",
    "Notes": "",
    "Output": "Agent alive and reachable",
    "ServiceID": "",
    "ServiceName": "",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 5,
    "ModifyIndex": 5
  },
  {
    "Node": "consul-server2",
    "CheckID": "serfHealth",
    "Name": "Serf Health Status",
    "Status": "passing",
    "Notes": "",
    "Output": "Agent alive and reachable",
    "ServiceID": "",
    "ServiceName": "",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 10,
    "ModifyIndex": 10
  },
  {
    "Node": "consul-server3",
    "CheckID": "serfHealth",
    "Name": "Serf Health Status",
    "Status": "passing",
    "Notes": "",
    "Output": "Agent alive and reachable",
    "ServiceID": "",
    "ServiceName": "",
    "ServiceTags": [],
    "Definition": {},
    "CreateIndex": 8,
    "ModifyIndex": 8
  }
]

any可以更换成其他状态：any, passing, warning, or critical。

4.2.2 获取所有服务

文档：List Services

$ curl http://127.0.0.1:18500/v1/catalog/services | jq .

结果：

{
  "consul": [],
  "gateway": [],
  "server": []
}

4.2.3 根据服务名获取所有对应的服务节点

文档：List Nodes for Service

$ curl http://127.0.0.1:18500/v1/catalog/service/:service_name | jq .

server的结果：

[
  {
    "ID": "f33332e4-3881-b975-d647-bc21a4ca41da",
    "Node": "consul-client1",
    "Address": "172.26.0.8",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "172.26.0.8",
      "wan": "172.26.0.8"
    },
    "NodeMeta": {
      "consul-network-segment": ""
    },
    "ServiceKind": "",
    "ServiceID": "1fw20gk4kq30tk",
    "ServiceName": "server",
    "ServiceTags": [],
    "ServiceAddress": "fullstack_server2",
    "ServiceWeights": {
      "Passing": 1,
      "Warning": 1
    },
    "ServiceMeta": {},
    "ServicePort": 50051,
    "ServiceEnableTagOverride": false,
    "ServiceProxy": {
      "MeshGateway": {}
    },
    "ServiceConnect": {},
    "CreateIndex": 26,
    "ModifyIndex": 26
  },
  {
    "ID": "feaba61d-83ce-a7e6-3e99-f1b2fa889bf8",
    "Node": "consul-client2",
    "Address": "172.26.0.7",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "172.26.0.7",
      "wan": "172.26.0.7"
    },
    "NodeMeta": {
      "consul-network-segment": ""
    },
    "ServiceKind": "",
    "ServiceID": "1fw20hk4kq30n8",
    "ServiceName": "server",
    "ServiceTags": [],
    "ServiceAddress": "fullstack_server3",
    "ServiceWeights": {
      "Passing": 1,
      "Warning": 1
    },
    "ServiceMeta": {},
    "ServicePort": 50051,
    "ServiceEnableTagOverride": false,
    "ServiceProxy": {
      "MeshGateway": {}
    },
    "ServiceConnect": {},
    "CreateIndex": 24,
    "ModifyIndex": 24
  },
  {
    "ID": "feaba61d-83ce-a7e6-3e99-f1b2fa889bf8",
    "Node": "consul-client2",
    "Address": "172.26.0.7",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "172.26.0.7",
      "wan": "172.26.0.7"
    },
    "NodeMeta": {
      "consul-network-segment": ""
    },
    "ServiceKind": "",
    "ServiceID": "eewk9hk4kq2uvy",
    "ServiceName": "server",
    "ServiceTags": [],
    "ServiceAddress": "fullstack_server1",
    "ServiceWeights": {
      "Passing": 1,
      "Warning": 1
    },
    "ServiceMeta": {},
    "ServicePort": 50051,
    "ServiceEnableTagOverride": false,
    "ServiceProxy": {
      "MeshGateway": {}
    },
    "ServiceConnect": {},
    "CreateIndex": 22,
    "ModifyIndex": 22
  }
]

4.2.4 根据service id获取具体信息

文档：Get Service Configuration

需要注意，这个操作只能获取所查询agent（某个client）上注册的服务的信息。下面举两个例子，刚才有说到fullstack_server2是注册在fullstack_consul_client1上的；而fullstack_server3是注册在fullstack_consul_client2上的。

fullstack_server2

# 首先需要登入到docker network中的某台机器上，因为client都没有向主机暴露端口
# docker exec -it fullstack_consul_server1 /bin/sh
$ curl http://fullstack_consul_client1:8500/v1/agent/service/1fw20gk4kq30tk | jq .

结果：

{
  "ID": "1fw20gk4kq30tk",
  "Service": "server",
  "Tags": [],
  "Meta": {},
  "Port": 50051,
  "Address": "fullstack_server2",
  "Weights": {
    "Passing": 1,
    "Warning": 1
  },
  "EnableTagOverride": false,
  "ContentHash": "b13f5888fa84e5d"
}

fullstack_server3

# 首先需要登入到docker network中的某台机器上，因为client都没有向主机暴露端口
# docker exec -it fullstack_consul_server1 /bin/sh
$ curl http://fullstack_consul_client2:8500/v1/agent/service/1fw20hk4kq30n8 | jq .

结果：

{
  "ID": "1fw20hk4kq30n8",
  "Service": "server",
  "Tags": [],
  "Meta": {},
  "Port": 50051,
  "Address": "fullstack_server3",
  "Weights": {
    "Passing": 1,
    "Warning": 1
  },
  "EnableTagOverride": false,
  "ContentHash": "120b74b874209fe8"
}

4.2.5 删除某个服务的注册

文档：Deregister Service

做开发的时候，为了测试，有的时候需要手动删除某些服务，这时候就要用到这个接口了。

$ curl --request PUT http://127.0.0.1:18500/v1/agent/service/deregister/:service_id | jq .

4.3 UI

访问：http://127.0.0.1:18500，就会开启管理UI。

实际功能非常有限，主要是观察下集群及服务的状况。

4.4 Template

Consul有一个非常好用的功能就是能把注册的服务，通过一个模板，生成配置文件并输出到指定的位置。最常见的使用案例就是consul配合nginx，多个业务服务跑在后台，注册到consul，通过consul将业务后台的信息生成成nginx配置文件。同时，任何业务后台的变动都会触发配置文件的重新生成。consul的template还可以指定一个外部命令，在刚才提到的例子中就可以触发nginx的reload，使改变的配置文件生效。

template有单独的镜像：hashicorp/consul-template

范例nginx配置模板，文件位置：./vendor/consul/nginx

{{range services}} {{$name := .Name}} {{$service := service .Name}} {{ if eq $name "gateway" }}
upstream gateway {
    {{range $service}}server {{.Address}}:{{.Port}} max_fails=3 fail_timeout=60 weight=1;
    {{else}}server 127.0.0.1:65535; # force a 502{{end}}
} {{end}} {{end}}

server {
    listen 80;
    server_name localhost;

    access_log /var/log/nginx/fullstack.access.log;
    error_log /var/log/nginx/fullstack.error.log;

    root /usr/share/nginx/html;

    index index.html index.htm index.nginx-debian.html;

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }

    location / {
        proxy_set_header x-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header HOST $http_host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_redirect http:// https://;
        proxy_connect_timeout 240;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
        proxy_pass http://gateway;
    }
}

template启动：

$ docker run --rm -it --name templateX \
    -v ./vendor/consul/nginx:/tmp/nginx.ctmpl \ # 将模板配置文件映射到容器内
    -v /tmp/template:/consul-template/data \    # 将主机的临时文件夹映射到容器内配置文件的生成位置，方便后续在主机上直接查看生成的配置文件
    hashicorp/consul-template:0.22.1-alpine \
    -dry \
    -log-level=debug \
    -consul-addr=host.docker.internal:18500 \
    -consul-retry \
    -consul-retry-attempts=5 \
    -consul-retry-backoff=500ms \
    -template=/tmp/nginx.ctmpl:/consul-template/data/default.conf

查看生成的：/tmp/template/default.conf

upstream gateway {
    server fullstack_gateway3:3000 max_fails=3 fail_timeout=60 weight=1;
    server fullstack_gateway1:3000 max_fails=3 fail_timeout=60 weight=1;
    server fullstack_gateway2:3000 max_fails=3 fail_timeout=60 weight=1;

}

server {
    listen 80;
    server_name localhost;

    access_log /var/log/nginx/fullstack.access.log;
    error_log /var/log/nginx/fullstack.error.log;

    root /usr/share/nginx/html;

    index index.html index.htm index.nginx-debian.html;

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }

    location / {
        proxy_set_header x-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header HOST $http_host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_redirect http:// https://;
        proxy_connect_timeout 240;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
        proxy_pass http://gateway;
    }
}

4.5 DNS

官方文档：DNS Interface。

使用上应该说是非常简便了，而且基本上对业务没什么侵入性。我之前做的实验项目里没使用这个功能，主要是因为需要改动主机的DNS，比较麻烦。

4.6 Application

Consul有不少语言对应的客户端，我的实验项目用过node.js的：Consul。

注册服务：

import * as Consul from "consul";
import * as exitHook from "async-exit-hook";

const serviceId: string = uniqid();
const consul = new Consul({
    host: CONSUL_HOST, // fullstack_consul_client2
    port: CONSUL_PORT, // 8500
    promisify: true,
});

const register = async () => {
    const serverConf = Config.get().getRaw().server;
    await consul.agent.service.register({
        name: serverConf.serviceName, // server
        id: serviceId,
        address: SERVICE_HOST,        // fullstack_server3
        port: serverConf.servicePort, // 50051
        check: {
            http: `http://${SERVICE_HOST}:${serverConf.webPort}/health`, // http://fullstack_server3:50052/health
            interval: "10s",
            ttl: "15s",
        },
    });
};

const cleanup = (done: () => void) => {
    consul.agent.service.deregister(serviceId)
        .then(() => {
            console.log("cleanup done");
            done();
        })
        .catch((err) => {
            console.log(err);
            done();
        });
};

// exit
exitHook.forceExitTimeout(500); // wait 0.5s before force exit
exitHook((done: () => void) => {
    console.log("Process::exitHook - Got exit signal");
    cleanup(done);
});

// start
startServer().then(() => startWeb()).then(() => register()).catch((err) => console.log(err));

在服务启动的时候进行注册，并且记得要处理程序退出，退出的时候需要将注册信息删除，否则即便应用程序退出了，在consul里那个服务还是存在的。

客户端获取可用节点：

const consul = new Consul({
    host: CONSUL_HOST,
    port: CONSUL_PORT,
    promisify: true,
});

const servers = await consul.health.service({
    service: CONFIG.getRaw().server.serviceName, // server
    passing: true,                               // get only living nodes
}) as IResHealthService[];

// ...

4.7 Health Check

官方文档：Checks

在4.6的范例里也提到了，在注册服务的时候可以提供当前注册进consul的应用程序的健康检查设置，consul会使用HTTP请求来检查该URL，只要是200返回就表示该服务仍旧存活。

Appendix

资料

consul agent —help {#ID_APP_AGENT_HELP}

docker run -it --rm consul:1.6.1 agent --help
Usage: consul agent [options]

  Starts the Consul agent and runs until an interrupt is received. The
  agent represents a single node in a cluster.

HTTP API Options

  -datacenter=<value>
     Datacenter of the agent.

Command Options

  -advertise=<value>
     Sets the advertise address to use.

  -advertise-wan=<value>
     Sets address to advertise on WAN instead of -advertise address.

  -allow-write-http-from=<value>
     Only allow write endpoint calls from given network. CIDR format,
     can be specified multiple times.

  -alt-domain=<value>
     Alternate domain to use for DNS interface.

  -bind=<value>
     Sets the bind address for cluster communication.

  -bootstrap
     Sets server to bootstrap mode.

  -bootstrap-expect=<value>
     Sets server to expect bootstrap mode.

  -check_output_max_size=<value>
     Sets the maximum output size for checks on this agent

  -client=<value>
     Sets the address to bind for client access. This includes RPC, DNS,
     HTTP, HTTPS and gRPC (if configured).

  -config-dir=<value>
     Path to a directory to read configuration files from. This
     will read every file ending in '.json' as configuration in this
     directory in alphabetical order. Can be specified multiple times.

  -config-file=<value>
     Path to a file in JSON or HCL format with a matching file
     extension. Can be specified multiple times.

  -config-format=<value>
     Config files are in this format irrespective of their extension.
     Must be 'hcl' or 'json'

  -data-dir=<value>
     Path to a data directory to store agent state.

  -dev
     Starts the agent in development mode.

  -disable-host-node-id
     Setting this to true will prevent Consul from using information
     from the host to generate a node ID, and will cause Consul to
     generate a random node ID instead.

  -disable-keyring-file
     Disables the backing up of the keyring to a file.

  -dns-port=<value>
     DNS port to use.

  -domain=<value>
     Domain to use for DNS interface.

  -enable-local-script-checks
     Enables health check scripts from configuration file.

  -enable-script-checks
     Enables health check scripts.

  -encrypt=<value>
     Provides the gossip encryption key.

  -grpc-port=<value>
     Sets the gRPC API port to listen on (currently needed for Envoy xDS
     only).

  -hcl=<value>
     hcl config fragment. Can be specified multiple times.

  -http-port=<value>
     Sets the HTTP API port to listen on.

  -join=<value>
     Address of an agent to join at start time. Can be specified
     multiple times.

  -join-wan=<value>
     Address of an agent to join -wan at start time. Can be specified
     multiple times.

  -log-file=<value>
     Path to the file the logs get written to

  -log-level=<value>
     Log level of the agent.

  -log-rotate-bytes=<value>
     Maximum number of bytes that should be written to a log file

  -log-rotate-duration=<value>
     Time after which log rotation needs to be performed

  -log-rotate-max-files=<value>
     Maximum number of log file archives to keep

  -node=<value>
     Name of this node. Must be unique in the cluster.

  -node-id=<value>
     A unique ID for this node across space and time. Defaults to a
     randomly-generated ID that persists in the data-dir.

  -node-meta=<key:value>
     An arbitrary metadata key/value pair for this node, of the format
     `key:value`. Can be specified multiple times.

  -non-voting-server
     (Enterprise-only) This flag is used to make the server not
     participate in the Raft quorum, and have it only receive the data
     replication stream. This can be used to add read scalability to
     a cluster in cases where a high volume of reads to servers are
     needed.

  -pid-file=<value>
     Path to file to store agent PID.

  -protocol=<value>
     Sets the protocol version. Defaults to latest.

  -raft-protocol=<value>
     Sets the Raft protocol version. Defaults to latest.

  -recursor=<value>
     Address of an upstream DNS server. Can be specified multiple times.

  -rejoin
     Ignores a previous leave and attempts to rejoin the cluster.

  -retry-interval=<value>
     Time to wait between join attempts.

  -retry-interval-wan=<value>
     Time to wait between join -wan attempts.

  -retry-join=<value>
     Address of an agent to join at start time with retries enabled. Can
     be specified multiple times.

  -retry-join-wan=<value>
     Address of an agent to join -wan at start time with retries
     enabled. Can be specified multiple times.

  -retry-max=<value>
     Maximum number of join attempts. Defaults to 0, which will retry
     indefinitely.

  -retry-max-wan=<value>
     Maximum number of join -wan attempts. Defaults to 0, which will
     retry indefinitely.

  -segment=<value>
     (Enterprise-only) Sets the network segment to join.

  -serf-lan-bind=<value>
     Address to bind Serf LAN listeners to.

  -serf-lan-port=<value>
     Sets the Serf LAN port to listen on.

  -serf-wan-bind=<value>
     Address to bind Serf WAN listeners to.

  -serf-wan-port=<value>
     Sets the Serf WAN port to listen on.

  -server
     Switches agent to server mode.

  -server-port=<value>
     Sets the server port to listen on.

  -syslog
     Enables logging to syslog.

  -ui
     Enables the built-in static web UI server.

  -ui-content-path=<value>
     Sets the external UI path to a string. Defaults to: /ui/

  -ui-dir=<value>
     Path to directory containing the web UI resources.

consul —help

$ docker run -it --rm consul:1.6.1 --help
Usage: consul [--version] [--help] <command> [<args>]

Available commands are:
    acl            Interact with Consul's ACLs
    agent          Runs a Consul agent
    catalog        Interact with the catalog
    config         Interact with Consul's Centralized Configurations
    connect        Interact with Consul Connect
    debug          Records a debugging archive for operators
    event          Fire a new event
    exec           Executes a command on Consul nodes
    force-leave    Forces a member of the cluster to enter the "left" state
    info           Provides debugging information for operators.
    intention      Interact with Connect service intentions
    join           Tell Consul agent to join cluster
    keygen         Generates a new encryption key
    keyring        Manages gossip layer encryption keys
    kv             Interact with the key-value store
    leave          Gracefully leaves the Consul cluster and shuts down
    lock           Execute a command holding a lock
    login          Login to Consul using an auth method
    logout         Destroy a Consul token created with login
    maint          Controls node or service maintenance mode
    members        Lists the members of a Consul cluster
    monitor        Stream logs from a Consul agent
    operator       Provides cluster-level tools for Consul operators
    reload         Triggers the agent to reload configuration files
    rtt            Estimates network round trip time between nodes
    services       Interact with services
    snapshot       Saves, restores and inspects snapshots of Consul server state
    tls            Builtin helpers for creating CAs and certificates
    validate       Validate config files/directories
    version        Prints the Consul version
    watch          Watch for changes in Consul

使用Drone进行CI支持

Mon, 23 Dec 2019 02:36:22 GMT

1. 前言
2. 概念
3. 架构 & Multiple Pipeline & Parallelism
4. 使用

1. 前言

Drone是一个Golang技术栈的CI解决方案，功能和Jenkins之类的CI工具类似。

优点：

Golang编写，分发及搭建非常容易（镜像体积很小）
Golang编写，运行时占用资源极小（特指和Java栈的一系列工具比较）
构建运行时以镜像优先，保证在不同平台的构建结果一致
优秀的设计，支持插件化提供强大的功能支持
现代化的UI，开箱即用，甩开Jenkins之类有历史包袱的工具几条街

缺点：

较年轻，文档工作需要强化
插件的数量和质量，以及插件的文档支持需要强化
功能尚不能说强大，和Jenkins之类的老牌CI相比差距较大

简单选择：

Drone：
- 小型团队，对新技术适应能力较强的团队
- 对功能的丰富性要求并不是很高，但要求性能强大功能稳定
Jenkins：
- 对功能的丰富性要求较高，要求任何情况任何需求都能快速应对
- 运维人员对Jenkins非常熟悉可以很快上手使用

2. 概念

2.1 pipeline

pipeline是drone的核心概念
pipeline一般负责完成一个任务：构建、发布、部署，其内部会有多个行为共同组成一个pipeline
pipeline在drone里是进行分类的，按类型有多种种类，常用的有：
- docker：所有的构建行为都在临时docker容器内进行，跨平台保证行为一致
  - Environment Variables
- exec：所有的构建行为都在runner所在主机上进行，一般用在某些不方便放在容器内运行的工作，e.g xcode项目的构建
  - Environment Variables
- ssh：构建行为通过ssh执行远程命令进行
  - Environment Variables

2.2 step

pipeline里的每一个操作被称为step
组织多个step可以完成一个特定的pipeline，e.g
- 构建pipeline：clone、安装依赖、单元测试、打包、制作镜像、推送镜像

2.3 workspace

构建运行的工作空间，在不同的环境下其位置会有所不同
Posix系统（含docker容器），工作空间在：/tmp/drone-${RANDOM}/drone/src
OSX系统，工作空间在：/private/var/folders/...
Win系统，工作空间在：C:\windows\drone-%RANDOM%\drone\src
有一点要强调下，如果在bash脚本中访问当前pipeline的~或$HOME，获得的地址就是workspace的根目录，而不是当前runner的用户home
此外，workspace是临时的，会在pipeline创建的时候产生，并在完成的时候被销毁

2.4 trigger

trigger决定当前的pipeline是否要触发
trigger有很多类型：
- 根据分支：e.g 是否dev分支
- 根据事件：e.g 是否tag事件（注意，tag和分支trigger不能同时存在，因为tag是不区分分支的）
- 根据reference：e.g refs/tags/**
- 根据代码库：e.g octocat/hello-world
- 根据runner实例：e.g drone.instance1.com
- 根据状态触发：e.g failure

2.5 condition

condition决定当前的step是否要触发
condition有很多类型：
- 根据分支：e.g 是否dev分支
- 根据事件：e.g 是否tag事件（注意，tag和分支condition不能同时存在，因为tag是不区分分支的）
- 根据reference：e.g refs/tags/**
- 根据代码库：e.g octocat/hello-world
- 根据runner实例：e.g drone.instance1.com
- 根据状态触发：e.g failure

3. 架构 & Multiple Pipeline & Parallelism

3.1 架构

Drone这个CI其实很简单，也说不上什么架构。一般Drone会有一个单点Server，在git工具上注册好webhook接收事件，然后启动多个Runner来处理Server上产生的任务。这些Runner可以在同一台主机上，也可以分散在多台不同的主机上，官方文档的指引中要求不要将runner和server放在同一台主机上。

3.2 Multiple Pipeline

官方说明：

用途1：

在处理大型项目任务的时候，将任务拆散，分散到不同的物理机上进行并行处理，加速整个构建进程。如果是不同主机的话，需要用到2.4提到的pipeline trigger，将不同的pipeline设定好自己的运行目标主机。保证同一个repo在不同主机上触发的时候，只有当前主机（runner）应该执行的pipeline得到执行。

用途2：

确定pipeline之间的先后顺序，通过在pipeline一级定义depends_on来申明相互之间的依赖关系。这里特别需要注意的是：pipeline之间是不共享workspace的。所以每一步都需要单独做类似于依赖安装之类的工作，这需要特别小心。

---
kind: pipeline
# ...

---
kind: pipeline
name: p3

steps:
  - name: notify
  # ...

depends_on:
  - p1
  - p2

3.3 Parallelism

这部分内容与 Multiple Pipeline 的关系，和之前讲过的 trigger 与 condition 的关系一样。Multiple Pipeline 是pipeline级别的，而Parallelism则是step级别的，本质上仍旧是并行运行。

kind: pipeline
# ...

steps:
# ...

- name: s3
  commands:
    - # ...
  depends_on:
    - s1
    - s2

4. 使用

4.1 Server：安装 & 运行

4.1.1 OAuth2准备

需要在git repo软件上申请一个OAuth应用。这里我使用的是Gitea，就拿它来做演示：

点击：右上角头像 > 设置（下拉菜单） > 应用（页面中间），打开的页面是管理用户级别的Access Tokens和OAuth2应用的。

找到：创建新的 OAuth2 应用程序这一栏，输入：

应用名称：这名字后面用不到，填可理解的内容即可
重定向 URI：http://${drone_host}:${drone_ip}/login

点击创建应用。

在打开的页面上显示了OAuth2应用的相关信息，这里需要记下：

客户端ID
客户端秘钥

4.1.2 启动drone

Golang应用程序，使用上最容易的方式仍旧是镜像：drone/drone。

drone服务器启动时的环境变量文档在：Drone Documentation > Installation > Reference。

$ docker run -it -d \
    --name drone-server \
    -p 18980:80 \
    --log-driver=json-file \
    --log-opt max-size=512m \
    -v /tmp/drone/data:/data \ # sqlite db file
    -e DRONE_LOGS_DEBUG=true \
    -e DRONE_LOGS_COLOR=true \
    -e DRONE_LOGS_PRETTY=true \
    -e DRONE_LOGS_TRACE=true \
    -e DRONE_AGENTS_ENABLED=true \                                              # drone server running with no agents, start runners manually
    -e DRONE_GITEA_SKIP_VERIFY=true \                                           # gitea: use http protocol
    -e DRONE_GITEA_SERVER=http://host.docker.internal:13000 \                   # gitea: server address with protocol
    -e DRONE_GITEA_CLIENT_ID=fd023edb-7976-4d50-a92f-b16612683240 \             # gitea: oauth client id
    -e DRONE_GITEA_CLIENT_SECRET=S4Q6PktE3dKNHPUzZrTdyNJsTThwal4doUWf6jf4eRA= \ # gitea: oauth client secret 
    -e DRONE_RPC_SECRET=d9856af41ffe31f5e8025be020e981be \                      # drone: runner shall connect server with this secret
    -e DRONE_SERVER_HOST=host.docker.internal:18980 \                           # drone: server address without protocol
    -e DRONE_SERVER_PROTO=http \                                                # drone: server with http protocol
    drone/drone:1.6.3

4.1.3 OAuth2授权

访问drone的地址：http://host.docker.internal:18980，会跳转到gitea进行授权，授权完成后会跳转回drone。这时应该就已经以刚才制作OAuth2应用的用户身份登录drone了。

这里说明下，因为gitea和drone都运行在容器内，他们之间相互访问是通过容器名来进行的，而host主机访问这两者都是通过loopback地址，两者之间存在差异，会导致OAuth的过程失败。因此这里统一使用docker MAC desktop版本的host.docker.internal域名来贯通内部和外部。但需要额外修改host主机的/etc/hosts配置，把这个host解析为loopback地址。

4.1.4 UI同步 & 激活代码库

刚完成授权的账户是没有任何代码库的，打开drone首页发现是空列表（即便当前通过OAuth2授权的账号在gitea内有代码库）：

点击右上角的SYNC就会开始和gitea同步账户的代码库数据，完成后即可获得所有当前账号在gitea内所拥有的代码库列表：

这时候账号下的drone项目都是未激活状态，需要点击面板上项目右边的ACTIVATE进行激活：

点击SAVE保存即可。经过这几个操作，drone即激活了对这几个代码库的webhook事件监听。

至此为止drone本体的安装基本上完成了，后续还需要配置下runner。

4.1.5 API秘钥

点击右上角的用户头像，然后点击User settings会打开用户的设置页面。在这个页面上能找到用户的token。如果有需要使用drone API的话（或者是cli命令行工具），这个token是必须的。

4.2 Runner：安装 & 运行

4.2.1 安装

服务器设置完成后，如果没有单独安装和运行runner，服务器上所有触发的事件都会是Pending状态，而且没有任何日志。

关于Pending的debug，可以看下官方的一篇帖子：Builds are Stuck in Pending Status。

Runner的安装见官方文档：Drone Documentation > Installation > Runners。Runner也分不同的类型，一般常用的是：

Exec Runner：直接运行在主机上的runner
Docker Runner：运行在docker容器内的runner

Runner的类型和pipeline的类型并不要求一致，runner只是pipeline的运行者，不管是什么类型的pipeline，都可以在任何类型的runner上运作。举例来说，一个docker类型的pipeline，在exec runner上就会在主机上启动docker容器并运行，而docker runner则是直接在docker容器内运行。

4.2.2 运行

Exec Runner
Exec Runner需要手动在~/.drone-runner-exec/config创建一个配置文件：

DRONE_DEBUG=true
DRONE_LOG_FILE=/tmp/drone-runner-exec.txt
DRONE_LOG_FILE_MAX_SIZE=50
DRONE_RPC_DUMP_HTTP=true
DRONE_RPC_DUMP_HTTP_BODY=true
DRONE_RPC_PROTO=http
DRONE_RPC_HOST=host.docker.internal:18980
DRONE_RPC_SECRET=d9856af41ffe31f5e8025be020e981be
DRONE_RUNNER_PATH=$HOME/.yarn/bin:$HOME/.config/yarn/global/node_modules/.bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

更多的配置项可以查阅官方文档：Exec Runner > Installation > Configuration Reference。

配置文件里最重要的是DRONE_RPC_HOST``DRONE_RPC_SECRET这两项。修改完成后记得重启runner：

$ drone-runner-exec service stop && drone-runner-exec service start

Runner在执行pipeline操作时候的用户即是runner启动时的用户，这需要非常小心，否则会搞错用户导致权限错误。此外，在2.3 workspace的时候也提到过了，在runner执行pipeline的时候，~指向的是workspace的根目录，而不是用户的home，这点要非常小心。

举例来说，存放在$HOME/.docker下的凭证在exec runner运行的时候是不可访问的（~会定位到workspace而不是$HOME），这会导致私有registry的访问失败。同样的，pipeline运行时的PATH也不同于用户自身的PATH，需要在配置文件中设置好DRONE_RUNNER_PATH。

Docker Runner
这部分就非常简单了，无非就是一个docker容器，直接使用对应的官方镜像即可：drone/drone-runner-docker。

相关配置项可以查阅官方文档：Docker Runner > Installation > Configuration Reference。

4.3 UI秘钥设置

在执行pipeline的时候不可避免需要访问一些密码秘钥之类的信息，而构建过程中，理论上runner只能访问代码库里的内容。这就造成了问题，因为代码库并不是安全的存放秘钥的地方。针对这样的问题，drone有对应的解决方案。

在drone ui仓库的设置中，有一处：

设置完成后，就会保存在drone系统中：

后续在pipeline可以如下的形式进行访问：

kind: pipeline
name: default

steps:
- name: build
  image: alpine
  environment:
    USERNAME:
      from_secret: docker_username
    PASSWORD:
      from_secret: docker_password

更多关于secret的设置及访问，可以参见官方文档：Drone Documentation > Configuration > Secrets。在这方面，drone支持得非常全面，甚至外部的加密设施也可以支持访问。

4.4 私有Registry

在pipeline应用的过程中，比较常见的问题是对于私有registry的访问。毕竟现在的CI基本上都围绕着镜像打转，抓取镜像进行部署或者构建镜像向上推送都是常见需求。

官方对此也有解决方案：How to pull private images with 1.0。

4.5 部署 & 多点事件触发

上述的内容基本上把CI的最基础的应用都讲到了，如果只是简单的提交代码 > 触发webhook > drone pipeline这个流程的话，是没有问题的。

那么接下来就可以考虑下稍微复杂点的需求：

项目的构建和部署需要分开
构建定义为一个pipeline
部署定义为一个pipeline
部署pipeline应该由构建pipeline异步触发
部署pipeline应该和构建pipeline解耦，两者可能发生在完全隔离的两个物理机的runner上

然后我简单说下结论：在当前的版本（drone/drone:1.6.3），这个需求做不到，如果是按官方的API和功能的话。而使用一些非官方的hacking思路，则可以做到基本上一致的效果。

根据一开始说的，如果单独只是一个构建pipeline，很简单就能做到。而如果要实现刚才列出的需求，就需要在构建pipeline完成并退出之前触发一个额外的事件，只要能触发额外的事件，再配合上：trigger & condition，保证代码库的pipeline启动的时候，只有部署pipeline进入工作，且只有正确的runner实例进入工作，那一切就通了。

那么，能不能手动触发一个部署呢？研究了下官方的资料，发现正常途径基本上做不到，只有一些非正常的思路才可以做到。下面说下思路。

4.5.1 drone api | drone cli

首先想到的是看看官方的API中有没有可用的命令（cli实际上就是官方API的封装）：API文档、CLI文档。

发现官方有一个命令：

$ drone build promote --help
  NAME:
     drone build promote - promote a build
  
  USAGE:
     drone build promote [command options] <repo/name> <build> <environment>
  
  OPTIONS:
     --param value, -p value  custom parameters to be injected into the job environment. Format: KEY=value
     --format value           format output (default: "...")

结合.drone.yml使用：

kind: pipeline
type: exec
name: test

platform:
  os: darwin
  arch: amd64

steps:
  - name: test
    commands:
      - echo "tested"
    when:
      event:
        - tag

---
kind: pipeline
type: exec
name: build

platform:
  os: darwin
  arch: amd64

steps:
  - name: build
    commands:
      - echo "built"
    when:
      event:
        - tag

depends_on:
  - test

---
kind: pipeline
type: exec
name: notify

platform:
  os: darwin
  arch: amd64

steps:
  - name: notify
    commands:
      - drone build promote fullstack/gateway 100 production
    environment:
      DRONE_SERVER: http://host.docker.internal:18980
      DRONE_TOKEN: K5i8g6PMlLM3tWaPDRagigPkBrl1YKGu
    when:
      event:
        - tag

depends_on:
  - build

---
kind: pipeline
type: exec
name: deploy

platform:
  os: darwin
  arch: amd64

steps:
  - name: deploy
    commands:
      - echo "deployed"
    when:
      event:
        - promote
      target:
        - production

测试后发现，如果build参数给的是已经存在的构建的话，则会重复之前的构建流程；而如果给的是一个很大的不存在该build的值（比如上面举例的100），则构建在notify这一步失败，并报错：

+ drone build promote fullstack/gateway 100 production
client error 404: {"message":"sql: no rows in result set"}

查找了下相关资料，并没有找到官方文档，仅在论坛中找到几篇讨论：

根据官方人员的解释：

也就是说你只能对已经存在的build进行触发让这个已经测试构建完成的build进行部署，而不能从头创建一个新的build。也就是说，上述的工具能大致满足上面提出的那串需求，但本质上还是不同的：

测试构建等必须是一个单独的行为，需要先行做完，并形成一个完成的build
需要手动触发（因为你需要确认build号，所以这个行为必然是手动的，不可能自动化）这个完成的build，让yaml中配置为promote的event触发，进行部署

4.5.2 plugin

官方有一个插件叫：Downstream Build。乍看之下貌似是满足需求的，但我实际扒了下源码，发现这个插件的本质其实就是封装了下官方的API。所以实际上和4.5.1一样，不行。

4.5.3 webhook plugin

后续的思路是尝试使用webhook插件，在构建pipeline完成之后用webhook触发一个构建：Webhook。

文档工作总是半吊子，参数有几个根本不知道具体应该填什么，只能随便尝试下：

$ docker run --rm \
          -e PLUGIN_URLS=http://host.docker.internal:18980/hook \
          -e PLUGIN_USERNAME=root \
          -e PLUGIN_PASSWORD=Abcd1234_ \
          -e PLUGIN_DEBUG=true \
          -e PLUGIN_SKIP_VERIFY=true \
          -e DRONE_REPO_OWNER=fullstack \
          -e DRONE_REPO_NAME=gateway \
          -e DRONE_COMMIT_SHA=2087d78f48 \
          -e DRONE_COMMIT_BRANCH=master \
          -e DRONE_BUILD_EVENT=deployment \
          plugins/webhook:latest
Webhook 1
  URL: http://host.docker.internal:18980/hook
  METHOD: POST
  HEADERS: map[Authorization:[Basic cm9vdDpBYmNkMTIzNF8=] Content-Type:[application/json]]
  REQUEST BODY: {"repo":{"owner":"fullstack","name":"gateway"},"build":{"tag":"","event":"deployment","number":0,"commit":"2087d78f48","ref":"refs/heads/master","branch":"master","author":"","message":"","status":"success","link":"","started":0,"created":0}}

  RESPONSE STATUS: 200 OK
  RESPONSE BODY:

返回结果是200，正常，但结果本身为空。查看drone的UI发现实际上没有任何build被触发。这就很无奈了，这里的问题可能出在：

操作者：给的参数不正确
webhook插件：没有发送正确的webhook请求
drone服务器：忽略了不正确的webhook请求

无论如何，后续如果要继续的话就需要看源码了，插件的以及服务器的源码。

4.5.4 webhook fake

到这里就是非正常思路了。

因为gitea可以正常触发drone的webhook，思路就是使用curl仿造gitea的请求，发送到drone。其实drone官方也有对webhook的描述：How to use Global Webhooks，但实在是没什么正式的支持，API之类的易用性的工具都没有，只有这篇文章。

gitea官方有webhook相关的文档：Webhooks。

gitea的钩子可以在这里找到，点击下面的链接可以查看请求细节：

当然这也非常麻烦，而且gitea发送出去的webhook请求里有非常多repo详细信息，如果要做到自动化的话，这块的获取也是很麻烦的一件事情。

4.5.5 waiting hack

另一个非正常思路就是定义一个pipeline，仅在指定的runner上运行，然后命令中执行脚本，查询私有registry，看目标仓库（镜像）的目标tag是否存在，存在的话就进行部署。而在其他的runner上进行构建和镜像推送操作。

这样就能做到一开始提的需求，虽然恶心了点。

在Docker中使用Node

Wed, 11 Dec 2019 02:36:22 GMT

1. 前言
2. 镜像制作
3. 集群处理及反向代理
- 3.1 pm2 + nginx
- 3.2 docker-compose + nginx
4. 健康检查

1. 前言

在Docker中使用Node，中间遇到了相当多的问题，这里就简单记录下，以防忘记。下述的所有范例都是使用typescript进行逻辑编写的，并在Docker中进行编译制作镜像的，周知。

2. 镜像制作

2.1 npm

在Dockerfile里的npm安装记得要加上--unsafe-perm，具体可以看：grpc/grpc-node#604。

2.2 镜像制作

Docker的COPY命令是将命令对应的文件夹下的所有内容拷贝到目标位置，而不包含命令中的文件夹本身，这是必须先了解的基础。

一般来说node项目的资源都会比较多比较散，不会像go应用程序一样build完成之后就是一个binary文件，node会有很多零碎的文件和代码都必须拷贝到镜像里。这里就需要先制作一个context。

假设项目的文件夹结构如下：

/- 
 | bash /-              # bash脚本
 |       | compose.sh   # 制作compose配置文件的脚本
 |       | docker.sh    # 制作镜像的脚本
 | build                # 编译完成的js文件
 | node_modules         # npm包
 | schema               # sql文件
 | src                  # typescript源码
 | .gitignore
 | Dockerfile
 | package.json
 | config.yml
 | README.md
 | tsconfig.json
 | tslint.json
 | yarn.lock

则可以使用如下脚本制作一个context子集，并进行镜像制作：

#!/usr/bin/env bash

FULLPATH="$( cd "$(dirname "$0")" ; pwd -P )"
cd ${FULLPATH}/..

VERSION=`cat ./package.json | jq -r '.version'`

# prepare docker context
rm -rf ./docker                 # 删除之前的context，如果有的话
mkdir -p ./docker/context       # 制作context文件夹
mkdir -p ./docker/context/pm2   # 制作PM2日志文件夹，后面会说到
cp -r \                         # 拷贝制作镜像需要的资源到context内
    src \
    config.yml \
    package.json \
    tsconfig.json \
    tslint.json \
    yarn.lock \
    ./docker/context

# build image
docker build \
    --no-cache \
    --tag your_app_name:${VERSION} \
    --file ./Dockerfile \
    ./docker

# remove images without tags
docker rmi $(docker images | awk '/^<none>/ {print $3}')  # 当制作tag重复的镜像时，这个命令就很有用

# remove tmp file
rm -rf ./docker

# push image
ORIGIN_TAG="you_app_name:${VERSION}"
TARGET_TAG="your_dockerhub_account/you_app_name:${VERSION}"
docker tag ${ORIGIN_TAG} ${TARGET_TAG}
docker push ${TARGET_TAG}

2.3 镜像stage

node的镜像在制作过程中，需要一些命令进行辅助，而这些命令在基准的node镜像上是不存在的，因此就需要在Dockerfile中先npm安装它们。比如说typescript、yarn等。而这些安装行为都会显著增大镜像的体积，因此这里就需要使用到按stage进行构建的技术。

官方文档在：Use multi-stage builds。

先放一个例子：

FROM node:10.16.3-alpine as builder

WORKDIR /opt

COPY ./context ./

RUN npm i typescript -g --unsafe-perm && \
    npm i --only=prod --unsafe-perm --loglevel verbose && \
    tsc

FROM node:10.16.3-alpine

WORKDIR /app

COPY --from=builder /opt .

ENTRYPOINT ["node", "./build/index.js"]

该Dockerfile的上半部分将./context下的所有内容拷贝到/opt这个工作路径下。然后安装了typescript，并根据package.json的内容进行npm包的安装。接下来使用刚才安装好的typescript命令tsc根据tsconfig.json的配置将src文件夹下的源码编译为build文件夹下的js源码。

从下半部分的FROM node:10.16.3-alpine开始，起了一个干净的node镜像，并将builder这个阶段做好的内容从builder阶段的/opt文件夹下拷贝到/app下。这里仍旧需要注意COPY命令是不会拷贝目标文件夹自身的，只会拷贝文件夹下的内容。这样制作完成的镜像中就不会包含之前安装的typescript了。

这个例子简单了点，只有一个typescript，如果在构建过程中还要用到一些其他东西的话，效果（体积变化）就会非常明显。

3. 集群处理及反向代理

node作为一个单进程单线程的应用程序，在利用CPU上实在是不行，所以就需要一些外部程序的辅助来充分利用物理CPU。一般有两个解决方案。下述解决方案中的Nginx跑在容器里或跑在主机上都是可以的，没有任何区别。

3.1 pm2 + nginx

这个解决方案只需要启动一个应用程序容器，在容器内使用PM2对应用程序进行cluster化，由PM2监听单个端口并转发所有的进入请求。在应用程序容器之外，由Nginx处理所有到达主机的请求。

这里就涉及到在容器内使用PM2。首先需要安装PM2，需要在之前范例中的Dockerfile中的COPY --from=builder /opt .之后添加一行：RUN npm i pm2 -g --unsafe-perm --loglevel verbose。

然后在容器运行的ENTRYPOINT上，需要修改成：ENTRYPOINT ["pm2-runtime", "start", "./build/index.js"]。这里注意，启动命令中使用的不是pm2而是pm2-runtime。这个命令是为了在容器内使用而专门特化出来的，普通的pm2命令在启动后就会转后台，导致容器退出。

此外，在使用时可以附加一些参数：

docker run -d -it --name your_app_name \
    -p 3000:3000 \
    -v dir_of_host:/app/pm2 \                       # 映射到主机上的日志文件路径
    your_app_name:version \
    --name=your_app_name_in_pm2 \
    --instances=max \                               # 以cluster模式启动pm2，并按CPU数量启动node应用的进程
    --output=/app/pm2/your_app_name.stdout.log \    # 输出日志到pm2文件夹下，也就是之前在做context时特地做出来的文件夹
    --error=/app/pm2/your_app_name.stderr.log

3.2 docker-compose + nginx

这个方案比较粗暴，之前提到的Dockerfile不需要改动，容器仍旧只有一个进程一个线程，容器本身并不做任何改动。而是使用docker-compose命令启动多个容器，然后在Nginx中配置upstream来进行反向代理负载均衡。

使用如下bash脚本来生成compose配置文件：

#!/usr/bin/env bash

FULLPATH="$( cd "$(dirname "$0")" ; pwd -P )"
cd ${FULLPATH}/..

VERSION=`cat ./package.json | jq -r '.version'`

CONF=${FULLPATH}/../compose.yml

PROCESS_COUNT=8

PORT_BASE=3000

COMPOSE_TEMPLATE="$(cat <<-EOC
version: "2.1"

networks:
  net:
    driver: bridge

services:
EOC
)"

function generate_compose() {
    OUTPUT=${COMPOSE_TEMPLATE}

    for (( i=1; i<=${PROCESS_COUNT}; i++ ))
    do
        ID=${i}
        PORT="$((PORT_BASE + ID))"

        SERVICE_TEMPLATE="$(cat <<-EOS
  you_app_name_${ID}:
    image: your_dockerhub_account/you_app_name:${VERSION}
    container_name: you_app_name_${ID}
    hostname: you_app_name_${ID}
    networks:
      - net
    ports:
      - ${PORT}:3000
    logging:
      driver: json-file
      options:
        max-size: 512m
    restart: always
    volumes:
      - dir_of_host:/app/pm2
    command: [
      "--name=your_app_name_in_pm2_${ID}",
      "--instances=max",
      "--output=/app/pm2/your_app_name_${ID}.stdout.log",
      "--error=/app/pm2/your_app_name_${ID}.stderr.log"
    ]
EOS
)"

        NL=$'\n'
        OUTPUT="${OUTPUT}${NL}${SERVICE_TEMPLATE}"
    done

    echo "${OUTPUT}" > ${CONF}
}

generate_compose

当然也可以编写一个脚本来制作nginx的配置文件，这里就简略点，直接改了：

upstream upstream_node {
    server 127.0.0.1:3001 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3002 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3003 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3004 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3005 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3006 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3007 max_fails=3 fail_timeout=60 weight=1;
    server 127.0.0.1:3008 max_fails=3 fail_timeout=60 weight=1;
}

server {
    listen 80;

    listen 443 ssl;

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    ssl_certificate         cert/yourapp.youhost.com.key.pem;
    ssl_certificate_key     cert/yourapp.youhost.com.key;
    ssl_dhparam             cert/dhparam.pem;

    access_log /var/log/nginx/yourapp.youhost.com.access.log;
    error_log /var/log/nginx/yourapp.youhost.com.error.log;

    root /usr/share/nginx/html;

    index index.html index.htm;

    server_name yourapp.youhost.com;

    location / {
        proxy_set_header x-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header HOST $http_host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_redirect http:// https://;
        proxy_connect_timeout 240;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
        proxy_pass http://upstream_node;
    }
}

4. 健康检查

在容器内运行的node程序，可以设置一个专门用来进行健康检查的端点，然后在运行时进行配置，这样docker就可以了解程序是否存活。在配合consul等服务发现程序使用时，也可以使用该端点。

应用程序代码改动：

app.use(async (ctx: Koa.Context, next) => {
    if (ctx.path === "/health") {
        ctx.status = 200;
        ctx.body = "OK";
    }
    return next();
});

Docker compose yml改动：

restart: always
healthcheck:
  test: wget http://127.0.0.1:3000/health -q -O - > /dev/null 2>&1
  interval: 10s
  timeout: 20s
  retries: 10

在VirtualBox中安装Tor

Fri, 20 Sep 2019 02:36:22 GMT

1. 前言
2. VirtualBox
3. Linux
4. Tor

1. 前言

就是一篇简单的笔记。

2. VirtualBox

这块不需要很详细的讲解，基本上只要从官网下载binary直接使用即可。镜像需要提前下载好，VirtualBox安装比较奇怪的一点是，虚拟机的创建和操作系统的安装是分开的，会先创建出虚拟机实例，然后才是加载镜像进行虚拟机操作系统的安装。这点有点和其他的虚拟机不太相同。

VirtualBox虚拟机的显示自适应需要额外设置，比较麻烦。显示设置的屏幕里，需要把显卡控制器改成：VBoxSVGA。

3. Linux

这里使用的是Ubuntu Desktop版本，因为后续安装和使用Tor最简单的做法就是直接使用官方的Tor Browser，也正因此需要桌面版本的操作系统。如果对安全有更高的要求，可以使用FreeBSD操作系统。

软件安装：

$ sudo apt-get install build-essential
$ sudo apt-get install wget vim

安装virtualbox的辅助程序Devices > Insert Guest Additions CD Image。

按个人喜好，可选安装：sublime text3。

安装privoxy，用来给需要HTTP代理的应用程序做前置入口，将这些HTTP流量转为socks5流量，进入到tor：

$ sudo apt-get install privoxy

修改配置文件/etc/privoxy/config：添加forward-socks5 / localhost:9150 .。

后续可以在命令行下设置：

export http_proxy=http://127.0.0.1:8118
export https_proxy=http://127.0.0.1:8118

命令行流量就全走tor了。命令行下，可以使用curl ipinfo.io来查看当前IP的位置。

在tor安装成功之前，虚拟机肯定也是需要代理的，否则tor软件根本下不下来。可以通过Linux操作系统网络配置设置代理：

将所有的HTTP(s)代理设置成：192.168.xx.xx:xxxx，socks设置成192.168.xx.xx:xxxx。

命令行下则：

export http_proxy=http://192.168.xx.xx:xxxx
export https_proxy=http://192.168.xx.xx:xxxx

4. Tor

安装就直接从官网上下载Tor Browser，解压即可使用。配置文件位置：Browser/TorBrowser/Data/Tor/torrc。

国内使用的时候必须使用网桥，按软件提示直接选一个可用的网桥，或从数据库申请一个网桥即可。注意，从数据库申请下来的网桥不一定就是可用的，还是需要连接测试。如果有条件的话，可以在Tor Browser之前再自己做一个跳板，这样效果会好很多，无论是从隐匿性上来说，还是从可用性上来说。

Tor Browser在连接完成之后，会在本地打开一个端口9150，提供本地的socks5连接。但软件并不提供HTTP和HTTPS代理，需要之前提到过的privoxy软件进行转换即可。

对Tor的节点进行限制，直接在之前提到的配置文件里添加内容即可，注意不要修改网桥相关的配置内容，那些是软件自动生成添加的：

## 以下为排除的节点(StrictNodes 1为坚决执行)
ExcludeNodes {cn},{hk},{mo},{kp},{ir},{cu},{vn},{ru},{by},{sd},{kz},{uz},{pk},{kg},{tj},{tm},{tr},{sy},{sg},{th},{ph},{my},{lk}
ExcludeExitNodes {cn},{hk},{mo},{kp},{ir},{cu},{vn},{ru},{by},{sd},{kz},{uz},{pk},{kg},{tj},{tm},{tr},{sy},{sg},{th},{ph},{my},{lk}
#ExcludeNodes 是指排除节点，即把括号中的国家的节点从tor链路上除去
#ExcludeExitNodes 是指“排除“出口”节点”，即tor的出口节点要排除括号中的国家的节点

## 指定出口节点：
StrictNodes 1
ExitNodes {us}
#这里us是指限定美国的ip为出口ip，你可以改为任何国家，国家代码请参考：https://zh.wikipedia.org/zh-cn/ISO_3166-1

轻量级过滤：

ExcludeNodes {cn},{hk},{mo}
ExcludeExitNodes {cn},{hk},{mo},{kp},{ir},{cu},{vn},{sd},{pk},{sy}
StrictNodes 1

分布式系统实战

Sat, 13 Jul 2019 07:36:22 GMT

1. 前言
- 1.1 相关资源清单
2. 组件清单 {#COMPONENT_LIST}
3. 架构
4. 测试
5. 报告
- 5.1 第一次测试
- 5.2 第二次测试
Appendix
- 监控清单 {#MONITORING_LIST}
  - Host
  - Container
  - Memcached
  - MySQL
  - Prometheus
  - Kafka JMX
  - Kafka Exporter
  - Jaeger Agent
  - Jaeger Collector
  - Filebeat
  - Elasticsearch
  - Golang

1. 前言

分布式系统因其使用的组件较多，复杂度较高，较难掌握。常说，写出一个能跑的东西很简单，但要全面掌握一门技术，并能够在任何情况下解决其发生的问题，则要难得多得多。分布式系统的难，更多的在于使用的组件多，每一个组件如果都需要掌握其从设计到运行的一系列技术细节就非常困难。此外，分布式系统的监控和分析也很难，也是因其组件多造成的，一个请求流转于多个组件之间，就很难定位当问题发生的时候其源头何在。

在长期的工作中，一直都没有实地进行实践的机会（公司体量、投入、团队管理等各种因素），因此就萌生了自己做一个实践项目，然后在云服务器上部署进行测试实验的念头。在此付诸实行。

1.1 相关资源清单

下面将大量资料进行清单整理，方便后续取用。

1.1.1 实践代码 {#PRACTICE_CODE}

该项目的实际实践代码在：dist-system-practice/golang/src/dist-system-practice/。该处的README主要提供了：

应用程序（Web、Service、Consumer）的环境变量清单
开发环境的组件清单及端口描述
开发环境的部署及启动命令
代码文件结构描述

线上环境的部署、启动、测试、导出数据等功能的相关实现在脚本：cluster/src/index.ts。其功能及使用描述在：README.md。

线上服务器拓扑及服务网格相关的配置在：index.ts#L22。

Grafana数据导出相关配置在：index.ts#L151。

1.1.2 组件实验代码

部分组件的简单实验代码在：dist-system-practice/experiment/。

1.1.3 go语言实验代码

go语言的简单实验代码在：dist-system-practice/golang/src/experiment/。

1.1.4 组件专题

对于项目中使用到的一系列组件，我这里都做过比较深入的使用测试及调研，并制作了一系列的专题博文。可以参见列表：2. 组件清单。

2. 组件清单 {#COMPONENT_LIST}

实践项目中（计划）使用到了如下组件：

组件	角色	专题
Golang	应用程序	Golang Notes
MySQL	数据库	Draft
Memcached	缓存	Memcached Notes
Docker	底层容器	Docker Notes
Envoy	代理入口	Envoy Notes
gRPC	组件通讯	gRPC Notes
Kafka	消息队列	Kafka Notes
Prometheus	监控系统	Prometheus Notes
Grafana	监控UI	Grafana Notes
Jaeger	链路追踪	Jaeger Notes
Cassandra	数据库	Draft
Elasticsearch	聚合分析	Elasticsearch Notes
Kubernetes	容器管理	TODO
Istio	服务编排	TODO
Linux	操作系统	Draft

201902之前，Golang、Docker、Kafka、Elasticsearch、Grafana、Prometheus、Jaeger于我的相关积累基本为0，基本上完全没直接接触过（实践），而到了6月底，我已经可以很熟练启动、使用这些组件，更重要的是完全理解它们的设计、架构，以及性能和部分调优手段。

对于”程序”的理解，以及超快的学习速度和学习能力，才是程序员能够在软件行业一直活下去的关键，我一直如此深信。

3. 架构

因为是一个实验性项目，应用程序的逻辑和架构做的非常简单。

3.1 组件列表

Web：go语言编写的web服务器，整个集群的入口
Service：go语言编写的gRPC服务器，web收到请求后不进行任何业务实际处理，直接通过gRPC发到Service，由Service处理完成后返回
Consumer：go语言编写的Kafka消费者，处理部分Service安排到Kafka的异步任务
Kafka：负责将部分Service的运算进行消息入队，并分发给Consumer处理（异步、解耦）
MySQL：应用程序的存储服务
Memcached：应用程序的缓存服务
Filebeat：负责将Web、Service、Consumer产生的有用日志（过滤）上传到Elasticsearch集群
Elasticsearch、Kibana：负责将Web、Service、Consumer产生的业务日志索引入库，以便后续查询
Cassandra：Jaeger Tracing的存储服务
Jaeger（Agent、Collector、Query）：负责接收Web、Service、Consumer发出的Span、Trace数据，入库以便后续查询
*Exporter：负责将各组件的状态以HTTP的方式输出出来
Prometheus：将 *Exporter 输出的数据采集，并录入到时序数据库中，以便后续查询
Grafana：负责将各组件的观察需求固定化，对Prometheus时序数据库进行查询，绘制图表

3.1.1 部分未实践组件

部分列在2. 组件清单中的组件实际上并未实际使用。因时间和精力的原因，只能割舍掉了。

Envoy：整体业务过于简单，不存在在Web服务器之前架设Envoy的必要性；而内部架构也过于简单，不存在架设Envoy作为内部流量控制入口的必要性
Kubernetes：实践复杂度过高，因精力原因放弃
Istio：实践复杂度过高，因精力原因放弃

3.2 数据模型

整个业务流程中只涉及到一个数据模型：

type Work struct {
	Id            uint32
	Viewed        uint32
	AchievedCount uint32
	Achievement   string
	IsPlanned     bool
	PlannedAt     time.Time
	AchievedAt    time.Time
	Created       time.Time
	Updated       time.Time
}

Id：自增长主键，每一条Work数据唯一
Viewed：是一个累加的int型，每次/viewedAPI访问，该值+1
AchievedCount：是一个累加的int型，每次完成/planAPI的任务推送及Consumer的achievement更新之后，该值+1
Achievement：该值由Service的/planAPI推送任务到Kafka，然后由Consumer获取任务之后进行运算并更新
IsPlanned：状态标识，当/planAPI完成之后标记为true，当Consumer运算并更新完成后标记为false
PlannedAt：时间
AchievedAt：时间
Created：时间
Updated：时间

3.3 业务流程

Web服务器

应用程序的入口为go语言编写的web服务器（Web），提供5个API（所有的API都不要求提供WorkId，会在API内部自行随机一个WorkId进行处理，方便后续自动化测试）：

/work：获取Work数据，并返回
/viewed：获取Work数据，并返回Viewed值
/achievement：获取Work数据，并返回Achievement值
/plan：获取Work数据，并将任务安排到Kafka队列，更新IsPlanned以及PlannedAt字段的值
/api：根据设置好的概率（可配置）抽取上述4个接口中的一个进行执行，实际上的性能测试入口

Consumer消费者

Kafka的消费者为go语言编写的服务器，对消息进行处理：从Kafka中获取任务，根据Id获取Work数据，根据计算因子计算出Achievement字符串值，更新IsPlanned、AchievedAt、Achievement字段的值。

3.4 系统架构

*Exporter这部分比较简略，因为基本上每个组件都有自己的Exporter，要详实还原实际的架构这图就没法看了。因此就只简单列出了go app相关的几条线。

3.5 部署拓扑

因预算关系，Elasticsearch和Kafka集群的分布并不是特别理想，不过也只能这样了。此外，图中还少了一个Client节点，专门用来运行Vegeta压测客户端的，因比较简单这里就没有绘制上去。

4. 测试

4.1 测试目标 {#TEST_TARGET}

制定测试目标一般需要以下步骤：

固定拓扑架构：尽量按线上真实情景的拓扑架构进行测试，如果规模过大的话，可以按比缩小（虽然会失真）
设定业务指标：同时在线100万、PV10亿等
将业务指标转化为可测试的程序指标：QPS、DB Transaction/s

这样就可以针对可测试的程序指标进行测试了。

而更进一步的测试目标可以细分为两类：

测试指标达标：当前系统可以负载起目标需求，在此基础上还可以找出系统的最高负载瓶颈点，并提出优化方案
测试指标未达标：当前系统未可以负载起目标需求，需要找出系统的瓶颈，并提出优化方案；后续需要多轮测试以验证优化的执行情况

就当前的项目来说，因为是纯粹的模拟测试项目，所以不存在真实的业务需求和业务指标，因此无法设定具体的程序指标，也就无从谈起是否达标的问题。只能说通过测试慢慢摸索当前架构的性能峰值，以及瓶颈点：

4.2 测试硬件

这次的测试选用的是Linode的云服务器，在选择的时候首先考虑的当然是国内的服务商，但发现像我这样只需要短期使用资源的客户（几个小时到1天左右）国内的服务商的付费方式太糟糕了。一般来说国内的服务商都是按月付费，所谓的按时收费其单价换算下来要比按月付费高得多得多，因此实际上是不可用的。

海外服务商一开始考虑使用Vultr，毕竟性价比是最高的，但后来发现Vultr对客户有非常严格的限制，如果需要租用大量机器或高性能机器的话，需要发Ticket进行人工审核。不出意外，我这样短期租用的客户被拒了。最后只能选用Linode，Linode在这方面倒是没有额外的限制，随开随用。

实际使用的是Linode的16G机型：6 CPU、16G RAM、320G Storage。简单Benchmark结果如下：

$ wget -qO- bench.sh | bash

----------------------------------------------------------------------
CPU model            : AMD EPYC 7601 32-Core Processor
Number of cores      : 6
CPU frequency        : 2199.996 MHz
Total size of Disk   : 315.0 GB (2.2 GB Used)
Total amount of Mem  : 16040 MB (120 MB Used)
Total amount of Swap : 511 MB (0 MB Used)
System uptime        : 0 days, 0 hour 2 min
Load average         : 0.29, 0.22, 0.09
OS                   : Ubuntu 18.04.2 LTS
Arch                 : x86_64 (64 Bit)
Kernel               : 4.15.0-50-generic
----------------------------------------------------------------------
I/O speed(1st run)   : 892 MB/s
I/O speed(2nd run)   : 1.1 GB/s
I/O speed(3rd run)   : 1.0 GB/s
Average I/O speed    : 1014.1 MB/s
----------------------------------------------------------------------
Node Name                       IPv4 address            Download Speed
CacheFly                        205.234.175.175         144MB/s
Linode, Tokyo, JP               106.187.96.148          20.7MB/s
Linode, Singapore, SG           139.162.23.4            6.48MB/s
Linode, London, UK              176.58.107.39           9.71MB/s
Linode, Frankfurt, DE           139.162.130.8           15.4MB/s
Linode, Fremont, CA             50.116.14.9             205MB/s
Softlayer, Dallas, TX           173.192.68.18           44.9MB/s
Softlayer, Seattle, WA          67.228.112.250          44.8MB/s
Softlayer, Frankfurt, DE        159.122.69.4            4.92MB/s
Softlayer, Singapore, SG        119.81.28.170           8.21MB/s
Softlayer, HongKong, CN         119.81.130.170          10.4MB/s
----------------------------------------------------------------------
Node Name                       IPv6 address            Download Speed
Linode, Atlanta, GA             2600:3c02::4b           39.3MB/s
Linode, Dallas, TX              2600:3c00::4b           28.9MB/s
Linode, Newark, NJ              2600:3c03::4b           18.3MB/s
Linode, Singapore, SG           2400:8901::4b           5.36MB/s
Linode, Tokyo, JP               2400:8900::4b           20.5MB/s
Softlayer, San Jose, CA         2607:f0d0:2601:2a::4    95.4MB/s
...
----------------------------------------------------------------------

$ (curl -s wget.racing/nench.sh | bash) 2>&1 | tee nench.log

-------------------------------------------------
nench.sh v2019.06.29 -- https://git.io/nench.sh
benchmark timestamp:    2019-07-12 05:48:17 UTC
-------------------------------------------------

Processor:    AMD EPYC 7601 32-Core Processor
CPU cores:    6
Frequency:    2199.996 MHz
RAM:          15G
Swap:         511M
Kernel:       Linux 4.15.0-50-generic x86_64

Disks:
sda  319.5G  HDD
sdb    512M  HDD

CPU: SHA256-hashing 500 MB
2.962 seconds
CPU: bzip2-compressing 500 MB
6.310 seconds
CPU: AES-encrypting 500 MB
1.362 seconds

ioping: seek rate
min/avg/max/mdev = 62.2 us / 112.5 us / 2.94 ms / 75.5 us
ioping: sequential read speed
generated 16.5 k requests in 5.00 s, 4.03 GiB, 3.30 k iops, 824.3 MiB/s

dd: sequential write speed
1st run:    855.45 MiB/s
2nd run:    1049.04 MiB/s
3rd run:    1049.04 MiB/s
average:    984.51 MiB/s

IPv4 speedtests
your IPv4:    173.255.252.xxxx

Cachefly CDN:         175.13 MiB/s
Leaseweb (NL):        13.85 MiB/s
Softlayer DAL (US):   38.74 MiB/s
Online.net (FR):      11.06 MiB/s
OVH BHS (CA):         16.75 MiB/s

IPv6 speedtests
your IPv6:    2600:3c01::xxxx

Leaseweb (NL):        7.77 MiB/s
Softlayer DAL (US):   0.00 MiB/s
Online.net (FR):      8.44 MiB/s
OVH BHS (CA):         17.60 MiB/s
-------------------------------------------------

我是很想把CPU上到至少8个核，但囿于预算，还是降了一档。

4.3 测试规划

上面在4.1 测试目标的时候提到了设定目标需要固定程序拓扑架构，但即便在程序架构固定的情况下，仍旧有大量细节（参数、配置）是可以微调变动的：

客户端连接数量：最大连接数，越大的最大连接数意味着越高的并发请求可能，而提升并发意味着负载的显著上升
客户端请求速率：同时到达服务器的请求数量，即并发请求数量，并发数量的上升最终体现在这个指标的提升上
数据库表量级：不同数据量的数据库表，其性能也会显著不同，因此在测试的时候也可以变动下表数据量再进行测试
数据库连接：少量的连接不足以处理请求，但过大的连接数也会显著降低性能，这方面也是一个测试点
gRPC连接池容量：虽然gRPC的Go客户端对于并发的处理非常好，但连接池仍旧在某些情况下有其作用，如何找出合理的并发池容量也是可选的测试条目之一
Kafka目标Topic的分片数量：提升分片数量会降低写入的性能，但更多的分片意味着更多的消费者，消息的处理速度会上升
Elasticsearch集群的Node数量：提升节点会降低写入性能，但会提升查询性能
JVM设置：各个用到JVM的软件一般都需要很精细地对JVM进行配置和调优，才能很好地发挥性能，而这方面的配置变化对测试的影响也很大
消费者计算因子：随着因子数值的调大，计算量会显著上升，最终会体现在Consumer角色的负载上升，以及Kafka队列的堆积不能及时消费等

测试的规划制定需要固定大部分的变量、配置，仅修改少部分，然后进行多次测试，横向比较性能的变化，就可以找出当前架构的最佳性能表现设置。

4.4 监控清单

下面是一份当前程序架构中需要进行重点监控的程序指标清单。这部分太长了，我放到最后的Appendix > 监控清单里，以便不影响下文的阅读。

4.5 部署工程

部署工作：

在Linode服务商这里申请开服务器
因Linode不支持在开服务器的时候直接部署SSH Key，需要使用命令来部署：ssh-copy-id -i ~/.ssh/id_rsa.pub root@xxx.xxx.xxx.xxx
使用1.1.1 实践代码提到的线上部署脚本进行部署：
- ./cluster.sh —machine
- ./cluster.sh —image
- ./cluster.sh —deploy —machine-type=all
使用 ./cluster.sh —docker-ps —machine-type=all 来观察是否启动正常
打开 MONITER_IP:9090 来查看是否所有的监控节点都正常在线
打开 MONITER_IP:5601 来设置ES内的Index Pattern
使用 curl -v http://WEB_IP:8000/work 等入口测试是否正常运行

4.6 测试执行 & 报告制作

部署完成之后：

记录测试开始时间
修改cluster.sh内相关配置
运行 ./cluster.sh —stress —machine-type=all 获得测试命令
在Client Host上执行测试命令开始测试，并观察实时报表中的报错数及响应时长变化（如有大量错误和大量超时，需要中断测试，并查找原因）
打开 MONITER_IP:9090 观察监控节点是否正常在线
打开 MONITER_IP:3000 观察监控指标变化
在测试完成前，使用pprof获取30秒间隔的两份堆内存dump（Web、Service、Consumer都需要）：
- go tool pprof http://HOST:PORT/debug/pprof/heap
  - Saved profile in /Users/XXX/pprof/pprof.web.alloc_objects.alloc_space.inuse_objects.inuse_space.001.pb.gz
- go tool pprof -png /Users/XXX/pprof/pprof.web.alloc_objects.alloc_space.inuse_objects.inuse_space.001.pb.gz > web_heap.png
在测试完成之前，使用pprof获取30秒的CPU dump（Web、Service、Consumer都需要）：
- go tool pprof http://HOST:PORT/debug/pprof/profile?seconds=30
  - Saved profile in /Users/XXX/pprof/pprof.web.samples.cpu.001.pb.gz
- go tool pprof -png /Users/XXX/pprof/pprof.web.samples.cpu.001.pb.gz > web_cpu.png

测试完成后：

记录测试结束时间
修改cluster.sh内相关配置
使用 ./cluster.sh —report 导出测试结果数据
手动获取Elasticsearch数据，并填入到报表模板中
- 获取时间段内所有Web请求数量，与客户端报表中数值进行比对是否匹配
- 获取时间段内所有的Consumer请求数量，与Web请求中的 /plan 数量进行比对是否匹配
- 获取时间段内所有Web请求API类型的配比，与配置项中的数值进行比对是否匹配
手动获取Jaeger数据，并填入到报表模板中
- 时间段内各Web API的耗时图表
将压测执行客户端的报表数据填入到报表模板中
将之前导出的CPU和堆内存Profiling数据以图片形式导出，并填入到报表模板中
修改导出的报表模板，添加测试实际配置数据，并编写结论板块内容
将完工的所有内容提交到代码库中：
- cluster/report/XXXXX/images
- cluster/report/XXXXX/report_XXXXX.md
- cluster/report/XXXXX/pprof/* 导出的CPU和堆内存dump
- cluster/output/*

4.6.1 获取Elasticsearch（Kibana）数据

获取所有Web请求数：
- 打开Discover > dist-web-web-7.0.0-*
- 调整时间成绝对时间
- 查看左上角的Hit数：1,552 hits
获取所有Consumer请求数：
- 打开Discover > dist-consumer-consumer-7.0.0-*
- 调整时间成绝对时间
- 查看左上角的Hit数：81 hits
- 比率验证：81 / 1552 = 5.21%；OK
获取API GetWork请求数：
- 打开Discover > dist-web-web-7.0.0-*
- 调整时间成绝对时间
- 在Filter中输入：api: apiGetWork
- 查看左上角的Hit数：704 hits
- 比率验证：704 / 1552 = 45.36%；OK
获取API UpdateViewed请求数：
- 打开Discover > dist-web-web-7.0.0-*
- 调整时间成绝对时间
- 在Filter中输入：api: apiUpdateViewed
- 查看左上角的Hit数：364 hits
- 比率验证：364 / 1552 = 23.45%；OK
获取API GetAchievement请求数：
- 打开Discover > dist-web-web-7.0.0-*
- 调整时间成绝对时间
- 在Filter中输入：api: apiGetAchievement
- 查看左上角的Hit数：403 hits
- 比率验证：403 / 1552 = 25.96%；OK
获取API PlanWork请求数：
- 打开Discover > dist-web-web-7.0.0-*
- 调整时间成绝对时间
- 在Filter中输入：api: apiPlanWork
- 查看左上角的Hit数：81 hits
- 数量验证：与Consumer计数匹配；OK

P.S 使用level: error过滤条件查找错误日志，如果是没有上传日志的service服务等，则需要：

docker-machine ssh service
docker logs —tail 1000 app_service | grep ERROR

4.6.2 获取Jaeger数据

打开Jaeger Query
将Lookback设置为：Custom Time Range
设置Start Time和End Time
设置Service为：app.web
设置Operation为：
- Web.HandleApi.apiGetWork
- Web.HandleApi.apiUpdateViewed
- Web.HandleApi.apiGetAchievement
- Web.HandleApi.apiPlanWork
设置Limit Results为最大值1500
查看右上角的耗时分布图以及查询数
选择几个耗时比较大的个例，点击观察原因

5. 报告

经过实机测试，报告如下，有兴趣的可以打开看看：

5.1 第一次测试

1000qps测试发现瓶颈点（预设瓶颈，意料之中）Consumer CPU消耗过于剧烈。

5.2 第二次测试

解决Consumer的瓶颈问题，并对其进行验证。

因预算和时间等原因，后续并没有展开更多的测试，仅两次，一次演示问题的发现，一次演示问题的解决和验证。

Appendix

监控清单 {#MONITORING_LIST}

Host

Dashboard uid: 9CWBz0bik

Graph params:

var-interval=5s 调整图表的采样间隔，最低5s
var-env=All 固定值
var-name=All 固定值
var-node=192.168.3.111%3A9100 label_values(node_exporter_build_info,instance)
var-maxmount= 固定值
panelId=13 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

系统运行时间
- panelId=15
CPU 核数
- panelId=14
内存总量
- panelId=75
CPU使用率（5m）
- panelId=167
CPU iowait（5m）
- panelId=20
内存使用率
- panelId=172
当前打开的文件描述符
- panelId=16
根分区使用率
- panelId=166
系统平均负载
- panelId=13
磁盘总空间
- panelId=171
各分区可用空间
- panelId=164
CPU使用率、磁盘每秒的I/O操作耗费时间（%）
- panelId=7
内存信息
- panelId=156
磁盘读写速率（IOPS）
- panelId=161
磁盘读写容量大小
- panelId=168
磁盘IO读写时间
- panelId=160
网络流量
- panelId=157
TCP 连接情况
- panelId=158

Container

Dashboard uid: PV1XyHnWz

Graph params:

refresh=30s 不生效，但建议保留
var-containergroup=All 固定值
var-interval=30s 调整图表的采样间隔，最低30s
var-server=192.168.3.111 label_values(node_boot_time_seconds, instance) /([^:]+):.*/ 去掉了instance的port
var-name=prometheus 容器名
panelId=8 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Received Network Traffic per Container
- 容器收到的网络流量
- panelId=8
Sent Network Traffic per Container
- 容器发送的网络流量
- panelId=9
CPU Usage per Container
- 容器消耗的CPU
- panelId=1
Memory Usage per Container
- 容器消耗的内存
- panelId=10
Memory Swap per Container
- 容器的交换内存
- panelId=34

Memcached

Dashboard uid: NgzwcO7Zz

Graph params:

var-node=memcached-exporter%3A9150 label_values(memcached_up, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

% Hit ratio
- 命中率
- panelId=1
Connections
- 连接数
- panelId=4
Get / Set ratio
- Get Set比率
- panelId=3
Commands
- 按种类显示命令执行的数量
- panelId=2
evicts / reclaims
- Key驱逐数量
- panelId=8
Read / written bytes
- 网络流量
- panelId=6
Total memory usage
- 内存使用率
- panelId=7
Items in cache
- 内存中Key数量
- panelId=5

MySQL

Dashboard uid: MQWgroiiz

Graph params:

var-interval=1m 调整图表的采样间隔，最低1s
var-host=mysqld-exporter%3A9104 label_values(mysql_up, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

MySQL Connections
- 连接状态
- panelId=92
MySQL Aborted Connections
- 退出的连接统计
- panelId=47
MySQL Client Thread Activity
- 线程活动状态
- panelId=10
MySQL Thread Cache
- 线程池状态
- panelId=11
MySQL Questions
- 查询数量
- panelId=53
MySQL Slow Queries
- 慢查询数量
- panelId=48
MySQL Table Locks
- 表锁状态
- panelId=32
MySQL Network Traffic
- 网络流量统计
- panelId=9
MySQL Network Usage Hourly
- 网络流量统计/小时
- panelId=381
MySQL Internal Memory Overview
- 内部内存使用状态
- panelId=50
Top Command Counters
- 执行命令按种类分类数量
- panelId=14
Top Command Counters Hourly
- 命令数量/小时
- panelId=39
MySQL Query Cache Memory
- 缓存使用量
- panelId=46
MySQL Query Cache Activity
- 缓存命中状态
- panelId=45
MySQL File Openings
- 实时打开的文件数量
- panelId=43
MySQL Open Files
- 打开文件统计
- panelId=41

Prometheus

Dashboard uid: 54e7hO7Wk

Graph params:

var-job=prometheus 固定值
var-instance=prometheus 固定值
var-interval=1h 调整图表的采样间隔，最低1h
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Series Count
- 时序数量
- panelId=3
Failures and Errors
- 采样出错
- panelId=33
Appended Samples per Second
- 每秒采样数量
- panelId=4
Scrape Duration
- 采样耗时
- panelId=29
- 该图表按instance进行显示，因此如果需要查询某个特定服务的采样抓取耗时，需要调整该参数，不能固定使用prometheus
Prometheus Engine Query Duration Seconds
- 查询耗时情况
- panelId=15

Kafka JMX

Dashboard uid: chanjarster-jvm-dashboard

Graph params:

var-datasource=Prometheus 固定值
var-job=kafka 固定值
var-instance=kafka_1%3A7071 label_values(jvm_info{job=“$job”},instance)
var-mempool=All 固定值
var-memarea=All 固定值
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Open file descriptors
- 文件打开情况
- panelId=38
CPU load
- CPU使用情况，含JVM的统计区分
- panelId=29
Memory area [heap]
- 堆内存使用情况
- panelId=8
Memory area [nonheap]
- 堆外内存使用情况
- panelId=45
GC count increase
- GC数量
- panelId=6
GC time
- GC耗时
- panelId=5
Threads used
- 线程数量
- panelId=3
Physical memory
- 物理内存情况
- panelId=44

Kafka Exporter

Dashboard uid: jwPKIsniz

Graph params:

var-job=kafka-exporter 固定值
var-instance=kafka_exporter%3A9308 label_values(kafka_consumergroup_current_offset{job=~“$job”}, instance)
var-topic=All 固定值，可调整
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Message in per second
- 每秒消息数量
- panelId=14
Lag by Consumer Group
- 消费组延迟
- panelId=12
Message in per minute
- 每分钟消息数量
- panelId=16
Message consume per minute
- 每分钟消息消费
- panelId=18

Jaeger Agent

Dashboard uid: Z8ieXpnWk

Graph params:

var-node=jagent_web%3A5778 label_values(jaeger_agent_thrift_udp_server_queue_size, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Reporter batches submitted
- Reporter批量提交数（提交至collector）
- panelId=6
Reporter batches failures
- Reporter批量提交失败数
- panelId=8
Reporter spans submitted
- Reporter span提交数量
- panelId=10
Reporter spans failures
- Reporter span提交失败数
- panelId=12
Queue size
- Receiver等待队列（从app过来）
- panelId=24
Read errors
- ReceiverUDP读取错误数
- panelId=26
Packets processed
- Receiver处理的包数量
- panelId=20
Packets dropped
- Receiver丢弃的包数量
- panelId=22

Jaeger Collector

Dashboard uid: mb6-JR5iz

Graph params:

var-node=jcollector_1%3A14268 label_values(jaeger_collector_queue_length, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Traces received
- 收到的trace数量
- panelId=20
Traces rejected
- 拒绝的trace数量
- panelId=22
Spans received
- 收到的span数量
- panelId=18
Spans dropped
- 丢弃的span数量
- panelId=4
Spans rejected
- 拒绝的span数量
- panelId=24
Queue length
- 队列长度
- panelId=2
Span queue latency - 95 percentile
- span处理时长 95%
- panelId=10
Save latency - 95 percentile
- 数据库存储时长 95%
- panelId=26
Cassandra attempts
- cassandra数据库请求数量
- panelId=16
Cassandra errors
- cassandra数据库报错
- panelId=12

Filebeat

Dashboard uid: oF_Qr14Zz

Graph params:

var-node=filebeat_exporter%3A9479 label_values(filebeat_uptime_seconds, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Harvester
- 追踪文件的状态
- panelId=2
IO errors
- IO错误
- panelId=8
Filebeat events
- filebeat事件
- panelId=4
Output events
- 输出事件
- panelId=6
Pipeline events
- 管线事件
- panelId=10
Pipeline queue
- 管线队列
- panelId=12

Elasticsearch

Dashboard uid: FNysokSWk

Graph params:

var-interval=5m 调整图表的采样间隔，最低5m
var-cluster=es_cluster 固定值
var-name=es_1 label_values(elasticsearch_indices_docs{cluster=“$cluster”, name!=""},name)
var-instance=es_exporter%3A9114 固定值
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Pending tasks
- 集群未完成工作数
- panelId=16
Load average
- 节点负载
- panelId=30
CPU usage
- 节点CPU使用
- panelId=88
JVM memory usage
- 节点内存使用
- panelId=31
GC count
- GC次数
- panelId=7
GC time
- GC耗时
- panelId=27
Total translog operations
- 持久化操作数
- panelId=77
Total translog size in bytes
- 持久化容量
- panelId=78
Tripped for breakers
- 断路器触发次数
- panelId=79
Estimated size in bytes of breaker
- 断路器触发限制
- panelId=80
Disk usage
- 磁盘用量
- panelId=32
Network usage
- 网络用量
- panelId=47
Documents count on node
- 文档数量
- panelId=1
Documents indexed rate
- 文档索引数
- panelId=24
Documents merged rate
- 文档合并率
- panelId=26
Documents merged bytes
- 文档合并量
- panelId=52
Query time
- 查询耗时
- panelId=33
Indexing time
- 索引耗时
- panelId=5
Merging time
- 合并耗时
- panelId=3
Total Operations rate
- 所有操作速率
- panelId=48
Total Operations time
- 所有操作耗时
- panelId=49

Golang

Dashboard uid: ypFZFgvmz

Graph params:

var-job=go-apps 固定值
var-interval=1m 调整图表的采样间隔，最低1m
var-node=192.168.3.111%3A8000 label_values(go_memstats_alloc_bytes, instance)
panelId=1 根据图表，编号各自不同
width=1000&height=500 图表大小
tz=Asia%2FShanghai 用户时区

Sample graph link: link

Monitoring items:

Heap memory
- 堆内存用量
- panelId=1
Heap memory trends
- 堆内存申请和释放情况
- panelId=4
Heap objects
- 堆内存对象数量
- panelId=2
Heap system alloc
- 堆内存向系统申请和释放情况
- panelId=5
GC rate
- GC频次
- panelId=3
Next gc target
- 下次GC触发容量
- panelId=6
GC duration quantiles
- GC耗时情况，分25% 50% 90%三段
- panelId=8
Goroutines count
- goroutine数量
- panelId=7
Threads count
- 线程数量
- panelId=10

Memcached Notes

Sat, 11 May 2019 02:01:22 GMT

1. 前言
2. 清单
- 2.1 Mixi的系列博文
- 2.2 自撰的系列博文

1. 前言

早年对memcached有过一系列非常深入的研究分析，并形成了大量的文字积累。memcached这个软件在那么多年中也并没有什么很大的变化，毕竟它要服务的功能相对来说还是非常稳定的，就那么一小块，做好就好了。

因为文章年代都比较久远了，现在要找都需要到tag里去搜，就比较麻烦。因此在这里做一个综合，把所有的内容都罗列进来。

2. 清单

2.1 Mixi的系列博文

2.2 自撰的系列博文

Golang Pipeline

Fri, 10 May 2019 02:01:22 GMT

1. 前言
2. Channel实验范例
3. Go Concurrency Patterns: Pipelines and cancellation
资料
- 链接

1. 前言

学习一门新语言最简单的就是那些顺序执行的语言，会了PHP，换JAVA、Python、Ruby，无非就是语法更换下，上stackoverflow查下：“python字符串拼接”之类的，看下怎么写就完事了。难的是那些有特殊编程思维的语言，比如说JavaScript，异步原生，写代码要非常小心注意异步的返回如何处理，否则就会明明看着是先A后B，执行的时候却成了先B再A。就这方面来说，Go语言也属于后者，属于那种语法看会简单，实际学精很难的语言，而Golang难就难在goroutine以及channel带来的功能上。

之前在查看Go语言的gRPC第三方库的时候，其代码对channel的运用非常灵活：grpc-go-pool/pool.go。深感需要加深这块的理解。

在学习的时候，找到了一篇官方之前的博客，时间比较早了（2014年），但还算有用：Go Concurrency Patterns: Pipelines and cancellation。

不过语言还是一直在发展的，目前在进行批量的routine控制以及退出触发的方面，最佳的解决方案是context。

接下来，一点点开始。

2. Channel实验范例

在阅读官方博文之前，先自己着手做一些范例代码，加深对于Golang Basic > 2.4 通道 / 信道 channel的理解。

我做了点简单的演示范例：dist-system-practice/golang/src/experiment/channel/。

只需要结果的话，可以直接读README：dist-system-practice/golang/src/experiment/channel/README.md。

当中有几点比较有意思：

slice值进出channel之后，地址并没有改变，和pointer是一样的结果
channel在无buffer的情况下，很容易就会阻塞，导致routine睡眠，必须小心处理
带buffer的channel，在buffer耗尽之后也是同样的结果，实际上来说也必须小心阻塞
虽然向关闭的通道写数据会引起panic，但向关闭的通道读数据却不会，只会获得通道类型的默认值

有一张图，很好地将一系列状态以及操作结果整理了出来，可以参考：

3. Go Concurrency Patterns: Pipelines and cancellation

这里并不会通篇翻译：Go Concurrency Patterns: Pipelines and cancellation，有需要的可以看这篇。

此外，本章后半也会涉及到context，毕竟这家伙才是现在的准标准。

3.1 什么是Pipeline

通过输入channel从上游接收值
对这些数据执行某些函数，通常是生成一些新的值
通过输出channel发送值到下游

而在这一系列的交棒过程中，错误的发生和事务的取消是正常的情况，必须要进行处理，否则的话作为下游的routine可能会一直等待已经错误退出或取消事务的上游routine，导致资源泄露。使用的难点就在这里。

3.2 Cancel: Channel Done

官方博文中的代码范例写的非常散，因为有多处重复修改，这里提供一份完整拼接的版本：experiment/pipeline/pipeline.go。

官方博文通篇都阅读了的话，撇开行文中的Dummy业务逻辑不谈，可以了解到该文主要还是谈了如何对出问题的routine进行退出通知。官方的博文中使用的方法是申明一个类型为struct{}的Dummy通道，关闭该通道来进行退出消息的传送。

通过：

go func() {
	defer close(out) // HL
	for _, n := range nums {
		select {
		case out <- n:
		case <-done:
			return // HL
		}
	}
}()

以这样的方式，监听done通道的关闭，退出routine函数，并设置defer函数，在routine函数退出的时候，清理对应的资源并关闭通道。这种编码解决方法确实能解决问题，但非常难看，也没有层级退出的概念。

3.3 Cancel: Context

done通道确实能在功能上达到要求，但尚欠缺了一些要素，因此后续就有context这个包的出现。相关的学习可以阅读：快速掌握 Golang context 包，简单示例。此外，还有官方博客：Go Concurrency Patterns: Context。

一些概念和规范这里做下引用：

Context 的调用应该是链式的，通过WithCancel，WithDeadline，WithTimeout或WithValue派生出新的 Context。当父 Context 被取消时，其派生的所有 Context 都将取消。

通过context.WithXXX都将返回新的 Context 和 CancelFunc。调用 CancelFunc 将取消子代，移除父代对子代的引用，并且停止所有定时器。未能调用 CancelFunc 将泄漏子代，直到父代被取消或定时器触发。go vet工具检查所有流程控制路径上使用 CancelFuncs。

遵循以下规则，以保持包之间的接口一致，并启用静态分析工具以检查上下文传播。

不要将 Contexts 放入结构体，相反context应该作为第一个参数传入，命名为ctx。func DoSomething（ctx context.Context，arg Arg）error { // ... use ctx ... }
即使函数允许，也不要传入nil的 Context。如果不知道用哪种 Context，可以使用context.TODO()。
使用context的Value相关方法只应该用于在程序和接口中传递的和请求相关的元数据，不要用它来传递一些可选的参数
相同的 Context 可以传递给在不同的goroutine；Context 是并发安全的。

用法：

Done函数会返回一个channel，用来进行close通知（本质上还是之前的那一套）：

gen := func(ctx context.Context) <-chan int {
	go func() {
		select {
		case <-ctx.Done():
			return // returning not to leak the goroutine
		//...
		}
	}
//...
}
//...
ctx, cancel := context.WithCancel(context.Background())
defer cancel() // cancel when we are finished consuming integers

此外，还有一篇老王的：Golang之Context的迷思，可以好好读下。

资料

链接

Envoy Notes

Wed, 08 May 2019 02:01:22 GMT

1. 前言
2. 选型 & 比较
3. Benchmark
4. 架构
5. 使用
6. Admin {#ID_ADMIN}
7. 监控
8. TODO
资料
- 链接
- stats prometheus {#ID_APP_STATS}

1. 前言

Envoy应该说是云原生这个概念起来之后的代理应用No.1。在当前的发展趋势下，使用Envoy来解决代理需求应该是最佳方案。

中文手册：Envoy 官方文档中文版。当前（2019-05-07）Envoy的最新版本是1.10，和中文的文档之间有几个小版本的跨度，需要注意。

2. 选型 & 比较

作为新生代的代理应用，在使用之前必然会有一个为什么的疑问，为什么需要使用Envoy，它和Nginx以及HAProxy这类老牌代理应用相比，好在哪里。

有一篇不错的博文可以阅读下：Envoy vs NGINX vs HAProxy: Why the open source Ambassador API Gateway chose Envoy。作者最主要的Concern在于两点：

Nginx之类的其他软件，部分有商业版本和社区版本的区分，而社区版本普遍功能较为简陋，不能完全满足需求
HAProxy之类的老牌软件，因为各种原因，功能演进都非常缓慢，不能跟上日益高速发展的云原生技术

说穿了就是功能不足，无论是商业原因还是研发原因还是资源原因。

那么Envoy能提供什么功能：Envoy 是什么？。可以看到Envoy提供的功能实在是太强大了，基本上现在主流的Proxy需求在Envoy身上都能得到满足。

官方也有一篇横向比较：与类似系统比较。

3. Benchmark

功能之后就是性能，那么和老牌的Nginx以及HAProxy等比较起来，Envoy的性能又如何呢。这里可以看下：Benchmarking 5 Popular Load Balancers: Nginx, HAProxy, Envoy, Traefik, and ALB。

文章发布时间是：10 Dec 2018，应该说还是非常具有时效性的。

4. 架构

除了在Nginx中比较常见的作为流量入口的代理模式之外，Envoy还介绍了一种作为服务网格总线的架构模式：

这种设计将Envoy作为面向服务架构（SOA）内部的所有流量的通信总线来使用。此设计将服务和服务之间的关系遮蔽了起来，服务集群只需要知道自己的Envoy在哪里即可，后续的流量就全部交给Envoy，而Envoy之间则通过服务发现将整个服务网格链接起来。

5. 使用

5.1 镜像

一般使用镜像的方式进行安装：

docker pull envoyproxy/envoy:v1.10.0

启动：

docker run --rm -it -d \
    --name envoy-test \
    --network=envoy-test-net \
    -p 9901:9901 \
    -p 9988:9988 \
    -v ${PATH}/conf:/etc/envoy \
    -v ${PATH}/log:/tmp \
    envoyproxy/envoy:v1.10.0

镜像中配置文件的位置为：

/etc/envoy/envoy.yaml

可以通过volume进行对应的配置文件覆盖。

5.2 配置

因功能实在是太强大，Envoy的配置也就比较复杂，官方文档配置方面的总纲在：配置参考。

此外，因Envoy的消息都是通过Protobuf来进行设计的，因此可以查看源代码来阅读配置项：envoy/api/envoy/config/。

另外，官方代码库也给了很多配置范例：envoy/examples/。以及：几个sandbox范例：Sandbox。最适合新手查看的应该是：前端代理。

有一篇Migrating from NGINX to Envoy Proxy by envoyproxy相当不错。以范例的形式讲解了Nginx的配置如何翻译到Envoy。

几个重要的配置项：

细节这里就不展开了，实在是篇幅太大。简单的范例可以直接看官方给的例子。

5.3 负载均衡Front Proxy范例

简单的带负载均衡的Front Proxy范例可以看：dist-system-practice/experiment/envoy/。

踩过的几个坑：

监听端的地址都必须是0.0.0.0，不能是127.0.0.1，否则在容器里收不到外部请求
将其他的网络服务作为upstream使用时，必须与envoy连接在同一个docker network中
clusters配置中的端点地址可以使用其他docker容器的名字作为address

6. Admin {#ID_ADMIN}

在Envoy的配置中有一个admin节点可以用来配置admin功能访问：

admin:
  access_log_path: "/tmp/admin_access.log"
  profile_path: "/tmp/envoy.prof"
  address:
    socket_address:
      address: 127.0.0.1
      port_value: 9901

提供一些admin相关功能，文档可以看：Administration interface。功能列表东西还真不少。

需要注意：

7. 监控

监控一样可以使用Prometheus进行Metrics采集。Envoy在启动的时候必须配置6. Admin，然后就可以在http://127.0.0.1:9901/stats/prometheus获取到Metrics。

本文在最后的附录部分留了一份样例：stats prometheus。

8. TODO

Envoy的内部架构
Envoy的高可用设计
Envoy热加载的设计原理
Envoy的集群使用
Envoy的其他高级功能使用范例
Envoy的Metrics理解

资料

链接

stats prometheus {#ID_APP_STATS}

# TYPE envoy_listener_admin_http_downstream_rq_xx counter
envoy_listener_admin_http_downstream_rq_xx{envoy_response_code_class="1",envoy_http_conn_manager_prefix="admin"} 0
envoy_listener_admin_http_downstream_rq_xx{envoy_response_code_class="2",envoy_http_conn_manager_prefix="admin"} 1
envoy_listener_admin_http_downstream_rq_xx{envoy_response_code_class="4",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_listener_admin_downstream_cx_destroy counter
envoy_listener_admin_downstream_cx_destroy{} 0
# TYPE envoy_listener_admin_downstream_cx_total counter
envoy_listener_admin_downstream_cx_total{} 2
envoy_listener_admin_http_downstream_rq_xx{envoy_response_code_class="5",envoy_http_conn_manager_prefix="admin"} 0
envoy_listener_admin_http_downstream_rq_xx{envoy_response_code_class="3",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_listener_admin_downstream_pre_cx_timeout counter
envoy_listener_admin_downstream_pre_cx_timeout{} 0
# TYPE envoy_listener_admin_http_downstream_rq_completed counter
envoy_listener_admin_http_downstream_rq_completed{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_listener_admin_no_filter_chain_match counter
envoy_listener_admin_no_filter_chain_match{} 0
# TYPE envoy_cluster_manager_update_out_of_merge_window counter
envoy_cluster_manager_update_out_of_merge_window{} 0
# TYPE envoy_http_downstream_flow_control_resumed_reading_total counter
envoy_http_downstream_flow_control_resumed_reading_total{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_http2_total counter
envoy_http_downstream_cx_http2_total{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_listener_manager_listener_added counter
envoy_listener_manager_listener_added{} 1
# TYPE envoy_http_downstream_rq_overload_close counter
envoy_http_downstream_rq_overload_close{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_listener_manager_listener_create_success counter
envoy_listener_manager_listener_create_success{} 4
# TYPE envoy_http_downstream_cx_http1_total counter
envoy_http_downstream_cx_http1_total{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_stats_overflow counter
envoy_stats_overflow{} 0
# TYPE envoy_listener_manager_listener_create_failure counter
envoy_listener_manager_listener_create_failure{} 0
# TYPE envoy_http_downstream_cx_destroy_remote counter
envoy_http_downstream_cx_destroy_remote{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_non_relative_path counter
envoy_http_downstream_rq_non_relative_path{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_no_route counter
envoy_http_no_route{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_cluster_manager_cluster_updated counter
envoy_cluster_manager_cluster_updated{} 1
# TYPE envoy_http_rs_too_large counter
envoy_http_rs_too_large{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_tx_reset counter
envoy_http_downstream_rq_tx_reset{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_server_watchdog_mega_miss counter
envoy_server_watchdog_mega_miss{} 0
# TYPE envoy_access_log_file_flushed_by_timer counter
envoy_access_log_file_flushed_by_timer{} 14
# TYPE envoy_http_downstream_cx_rx_bytes_total counter
envoy_http_downstream_cx_rx_bytes_total{envoy_http_conn_manager_prefix="admin"} 1029
# TYPE envoy_http_downstream_flow_control_paused_reading_total counter
envoy_http_downstream_flow_control_paused_reading_total{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_completed counter
envoy_http_downstream_rq_completed{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_listener_manager_listener_removed counter
envoy_listener_manager_listener_removed{} 0
# TYPE envoy_http_downstream_rq_xx counter
envoy_http_downstream_rq_xx{envoy_response_code_class="4",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_access_log_file_reopen_failed counter
envoy_access_log_file_reopen_failed{} 0
# TYPE envoy_http_rq_direct_response counter
envoy_http_rq_direct_response{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_http_downstream_rq_ws_on_non_ws_route counter
envoy_http_downstream_rq_ws_on_non_ws_route{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_cluster_manager_cluster_updated_via_merge counter
envoy_cluster_manager_cluster_updated_via_merge{} 0
# TYPE envoy_cluster_manager_cluster_added counter
envoy_cluster_manager_cluster_added{} 1
# TYPE envoy_runtime_override_dir_exists counter
envoy_runtime_override_dir_exists{} 0
# TYPE envoy_http_downstream_rq_http2_total counter
envoy_http_downstream_rq_http2_total{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_response_before_rq_complete counter
envoy_http_downstream_rq_response_before_rq_complete{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_listener_manager_listener_modified counter
envoy_listener_manager_listener_modified{} 0
# TYPE envoy_runtime_deprecated_feature_use counter
envoy_runtime_deprecated_feature_use{} 21
# TYPE envoy_http_downstream_cx_idle_timeout counter
envoy_http_downstream_cx_idle_timeout{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_rq_redirect counter
envoy_http_rq_redirect{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_http_downstream_rq_too_large counter
envoy_http_downstream_rq_too_large{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_protocol_error counter
envoy_http_downstream_cx_protocol_error{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_timeout counter
envoy_http_downstream_rq_timeout{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_runtime_override_dir_not_exists counter
envoy_runtime_override_dir_not_exists{} 0
# TYPE envoy_runtime_load_error counter
envoy_runtime_load_error{} 0
# TYPE envoy_access_log_file_write_completed counter
envoy_access_log_file_write_completed{} 4
# TYPE envoy_http_no_cluster counter
envoy_http_no_cluster{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_http_rq_reset_after_downstream_response_started counter
envoy_http_rq_reset_after_downstream_response_started{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_server_watchdog_miss counter
envoy_server_watchdog_miss{} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="3",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_cluster_manager_cluster_removed counter
envoy_cluster_manager_cluster_removed{} 0
# TYPE envoy_server_debug_assertion_failures counter
envoy_server_debug_assertion_failures{} 0
# TYPE envoy_cluster_manager_update_merge_cancelled counter
envoy_cluster_manager_update_merge_cancelled{} 0
# TYPE envoy_http_downstream_cx_overload_disable_keepalive counter
envoy_http_downstream_cx_overload_disable_keepalive{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_upgrades_total counter
envoy_http_downstream_cx_upgrades_total{envoy_http_conn_manager_prefix="admin"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="1",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_tx_bytes_total counter
envoy_http_downstream_cx_tx_bytes_total{envoy_http_conn_manager_prefix="admin"} 5132
# TYPE envoy_http_downstream_cx_destroy counter
envoy_http_downstream_cx_destroy{envoy_http_conn_manager_prefix="admin"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="5",envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_destroy_local_active_rq counter
envoy_http_downstream_cx_destroy_local_active_rq{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_drain_close counter
envoy_http_downstream_cx_drain_close{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_http1_total counter
envoy_http_downstream_rq_http1_total{envoy_http_conn_manager_prefix="admin"} 2
# TYPE envoy_http_downstream_cx_destroy_active_rq counter
envoy_http_downstream_cx_destroy_active_rq{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_access_log_file_write_buffered counter
envoy_access_log_file_write_buffered{} 6
# TYPE envoy_http_downstream_cx_destroy_local counter
envoy_http_downstream_cx_destroy_local{envoy_http_conn_manager_prefix="admin"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="2",envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_http_rq_total counter
envoy_http_rq_total{envoy_http_conn_manager_prefix="async-client"} 0
# TYPE envoy_http_downstream_cx_total counter
envoy_http_downstream_cx_total{envoy_http_conn_manager_prefix="admin"} 2
# TYPE envoy_http_downstream_rq_total counter
envoy_http_downstream_rq_total{envoy_http_conn_manager_prefix="admin"} 2
# TYPE envoy_runtime_load_success counter
envoy_runtime_load_success{} 0
# TYPE envoy_cluster_manager_cluster_modified counter
envoy_cluster_manager_cluster_modified{} 0
# TYPE envoy_http_downstream_rq_rx_reset counter
envoy_http_downstream_rq_rx_reset{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_idle_timeout counter
envoy_http_downstream_rq_idle_timeout{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_delayed_close_timeout counter
envoy_http_downstream_cx_delayed_close_timeout{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_destroy_remote_active_rq counter
envoy_http_downstream_cx_destroy_remote_active_rq{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_ssl_total counter
envoy_http_downstream_cx_ssl_total{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_cluster_upstream_cx_idle_timeout counter
envoy_cluster_upstream_cx_idle_timeout{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_destroy_local counter
envoy_cluster_upstream_cx_destroy_local{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_close_notify counter
envoy_cluster_upstream_cx_close_notify{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_flow_control_paused_reading_total counter
envoy_cluster_upstream_flow_control_paused_reading_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_connect_timeout counter
envoy_cluster_upstream_cx_connect_timeout{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_xx counter
envoy_cluster_upstream_rq_xx{envoy_response_code_class="2",envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_rq_cancelled counter
envoy_cluster_upstream_rq_cancelled{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_overflow counter
envoy_cluster_upstream_cx_overflow{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_destroy_local_with_active_rq counter
envoy_cluster_upstream_cx_destroy_local_with_active_rq{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_internal_redirect_succeeded_total counter
envoy_cluster_upstream_internal_redirect_succeeded_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_subsets_fallback counter
envoy_cluster_lb_subsets_fallback{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_zone_routing_sampled counter
envoy_cluster_lb_zone_routing_sampled{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_connect_attempts_exceeded counter
envoy_cluster_upstream_cx_connect_attempts_exceeded{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_per_try_timeout counter
envoy_cluster_upstream_rq_per_try_timeout{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_tx_bytes_total counter
envoy_cluster_upstream_cx_tx_bytes_total{envoy_cluster_name="http_service"} 1065
# TYPE envoy_cluster_upstream_flow_control_resumed_reading_total counter
envoy_cluster_upstream_flow_control_resumed_reading_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_original_dst_host_invalid counter
envoy_cluster_original_dst_host_invalid{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_subsets_created counter
envoy_cluster_lb_subsets_created{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_external_upstream_rq_completed counter
envoy_cluster_external_upstream_rq_completed{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_cx_rx_bytes_total counter
envoy_cluster_upstream_cx_rx_bytes_total{envoy_cluster_name="http_service"} 715
# TYPE envoy_cluster_upstream_flow_control_backed_up_total counter
envoy_cluster_upstream_flow_control_backed_up_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_update_success counter
envoy_cluster_update_success{envoy_cluster_name="http_service"} 58
# TYPE envoy_cluster_update_no_rebuild counter
envoy_cluster_update_no_rebuild{envoy_cluster_name="http_service"} 56
# TYPE envoy_cluster_upstream_cx_destroy_remote_with_active_rq counter
envoy_cluster_upstream_cx_destroy_remote_with_active_rq{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_zone_cluster_too_small counter
envoy_cluster_lb_zone_cluster_too_small{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_zone_routing_all_directly counter
envoy_cluster_lb_zone_routing_all_directly{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_protocol_error counter
envoy_cluster_upstream_cx_protocol_error{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_external_upstream_rq_xx counter
envoy_cluster_external_upstream_rq_xx{envoy_response_code_class="2",envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_external_upstream_rq counter
envoy_cluster_external_upstream_rq{envoy_response_code="200",envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_rq_completed counter
envoy_cluster_upstream_rq_completed{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_update_attempt counter
envoy_cluster_update_attempt{envoy_cluster_name="http_service"} 58
# TYPE envoy_cluster_lb_recalculate_zone_structures counter
envoy_cluster_lb_recalculate_zone_structures{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_pending_overflow counter
envoy_cluster_upstream_rq_pending_overflow{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_bind_errors counter
envoy_cluster_bind_errors{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_retry_overflow counter
envoy_cluster_upstream_rq_retry_overflow{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq counter
envoy_cluster_upstream_rq{envoy_response_code="200",envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_lb_zone_number_differs counter
envoy_cluster_lb_zone_number_differs{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_none_healthy counter
envoy_cluster_upstream_cx_none_healthy{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_zone_no_capacity_left counter
envoy_cluster_lb_zone_no_capacity_left{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_update_failure counter
envoy_cluster_update_failure{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_timeout counter
envoy_cluster_upstream_rq_timeout{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_destroy_remote counter
envoy_cluster_upstream_cx_destroy_remote{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_max_requests counter
envoy_cluster_upstream_cx_max_requests{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_internal_redirect_failed_total counter
envoy_cluster_upstream_internal_redirect_failed_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_flow_control_drained_total counter
envoy_cluster_upstream_flow_control_drained_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_local_cluster_not_ok counter
envoy_cluster_lb_local_cluster_not_ok{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_rx_reset counter
envoy_cluster_upstream_rq_rx_reset{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_destroy counter
envoy_cluster_upstream_cx_destroy{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_subsets_selected counter
envoy_cluster_lb_subsets_selected{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_subsets_removed counter
envoy_cluster_lb_subsets_removed{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_http1_total counter
envoy_cluster_upstream_cx_http1_total{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_cx_connect_fail counter
envoy_cluster_upstream_cx_connect_fail{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_pending_total counter
envoy_cluster_upstream_rq_pending_total{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_lb_zone_routing_cross_zone counter
envoy_cluster_lb_zone_routing_cross_zone{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_healthy_panic counter
envoy_cluster_lb_healthy_panic{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_total counter
envoy_cluster_upstream_cx_total{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_cx_http2_total counter
envoy_cluster_upstream_cx_http2_total{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_destroy_with_active_rq counter
envoy_cluster_upstream_cx_destroy_with_active_rq{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_total counter
envoy_cluster_upstream_rq_total{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_rq_retry_success counter
envoy_cluster_upstream_rq_retry_success{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_lb_subsets_fallback_panic counter
envoy_cluster_lb_subsets_fallback_panic{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_pending_failure_eject counter
envoy_cluster_upstream_rq_pending_failure_eject{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_membership_change counter
envoy_cluster_membership_change{envoy_cluster_name="http_service"} 2
# TYPE envoy_cluster_upstream_rq_retry counter
envoy_cluster_upstream_rq_retry{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_retry_or_shadow_abandoned counter
envoy_cluster_retry_or_shadow_abandoned{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_maintenance_mode counter
envoy_cluster_upstream_rq_maintenance_mode{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_tx_reset counter
envoy_cluster_upstream_rq_tx_reset{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_update_empty counter
envoy_cluster_update_empty{envoy_cluster_name="http_service"} 0
# TYPE envoy_listener_http_downstream_rq_xx counter
envoy_listener_http_downstream_rq_xx{envoy_response_code_class="1",envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 0
envoy_listener_http_downstream_rq_xx{envoy_response_code_class="4",envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 0
# TYPE envoy_listener_downstream_cx_destroy counter
envoy_listener_downstream_cx_destroy{envoy_listener_address="0.0.0.0_9988"} 5
envoy_listener_http_downstream_rq_xx{envoy_response_code_class="3",envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 0
envoy_listener_http_downstream_rq_xx{envoy_response_code_class="2",envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 5
# TYPE envoy_listener_downstream_pre_cx_timeout counter
envoy_listener_downstream_pre_cx_timeout{envoy_listener_address="0.0.0.0_9988"} 0
envoy_listener_http_downstream_rq_xx{envoy_response_code_class="5",envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 0
# TYPE envoy_listener_http_downstream_rq_completed counter
envoy_listener_http_downstream_rq_completed{envoy_http_conn_manager_prefix="ingress_http",envoy_listener_address="0.0.0.0_9988"} 5
# TYPE envoy_listener_no_filter_chain_match counter
envoy_listener_no_filter_chain_match{envoy_listener_address="0.0.0.0_9988"} 0
# TYPE envoy_listener_downstream_cx_total counter
envoy_listener_downstream_cx_total{envoy_listener_address="0.0.0.0_9988"} 5
envoy_http_downstream_rq_tx_reset{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="5",envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_total{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_downstream_cx_destroy_remote_active_rq{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_http1_total{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_downstream_rq_overload_close{envoy_http_conn_manager_prefix="ingress_http"} 0
# TYPE envoy_http_tracing_random_sampling counter
envoy_http_tracing_random_sampling{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_no_route{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_destroy_remote{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_downstream_cx_protocol_error{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_response_before_rq_complete{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_rq_direct_response{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_flow_control_resumed_reading_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_destroy_local_active_rq{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_http1_total{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_rq_reset_after_downstream_response_started{envoy_http_conn_manager_prefix="ingress_http"} 0
# TYPE envoy_http_tracing_service_forced counter
envoy_http_tracing_service_forced{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_overload_disable_keepalive{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_ws_on_non_ws_route{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="3",envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_rx_bytes_total{envoy_http_conn_manager_prefix="ingress_http"} 390
envoy_http_downstream_cx_idle_timeout{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="1",envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_idle_timeout{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_rs_too_large{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_completed{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_no_cluster{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_destroy_local{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_rx_reset{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_rq_total{envoy_http_conn_manager_prefix="ingress_http"} 5
# TYPE envoy_http_tracing_not_traceable counter
envoy_http_tracing_not_traceable{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_tx_bytes_total{envoy_http_conn_manager_prefix="ingress_http"} 840
envoy_http_downstream_cx_delayed_close_timeout{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_drain_close{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_flow_control_paused_reading_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_timeout{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_destroy{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_rq_redirect{envoy_http_conn_manager_prefix="ingress_http"} 0
# TYPE envoy_http_tracing_health_check counter
envoy_http_tracing_health_check{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="2",envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_downstream_cx_ssl_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_too_large{envoy_http_conn_manager_prefix="ingress_http"} 0
# TYPE envoy_http_tracing_client_enabled counter
envoy_http_tracing_client_enabled{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_xx{envoy_response_code_class="4",envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_upgrades_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_http2_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_non_relative_path{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_http2_total{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_destroy_active_rq{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_total{envoy_http_conn_manager_prefix="ingress_http"} 5
# TYPE envoy_listener_admin_downstream_pre_cx_active gauge
envoy_listener_admin_downstream_pre_cx_active{} 0
# TYPE envoy_listener_admin_downstream_cx_active gauge
envoy_listener_admin_downstream_cx_active{} 2
# TYPE envoy_http_downstream_cx_active gauge
envoy_http_downstream_cx_active{envoy_http_conn_manager_prefix="admin"} 2
# TYPE envoy_listener_manager_total_listeners_draining gauge
envoy_listener_manager_total_listeners_draining{} 0
# TYPE envoy_server_parent_connections gauge
envoy_server_parent_connections{} 0
# TYPE envoy_runtime_admin_overrides_active gauge
envoy_runtime_admin_overrides_active{} 0
# TYPE envoy_cluster_manager_active_clusters gauge
envoy_cluster_manager_active_clusters{} 1
# TYPE envoy_cluster_manager_warming_clusters gauge
envoy_cluster_manager_warming_clusters{} 0
# TYPE envoy_listener_manager_total_listeners_active gauge
envoy_listener_manager_total_listeners_active{} 1
# TYPE envoy_http_downstream_cx_http1_active gauge
envoy_http_downstream_cx_http1_active{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_server_uptime gauge
envoy_server_uptime{} 140
# TYPE envoy_server_memory_heap_size gauge
envoy_server_memory_heap_size{} 5242880
# TYPE envoy_server_days_until_first_cert_expiring gauge
envoy_server_days_until_first_cert_expiring{} 2147483647
# TYPE envoy_server_hot_restart_epoch gauge
envoy_server_hot_restart_epoch{} 0
# TYPE envoy_server_total_connections gauge
envoy_server_total_connections{} 0
# TYPE envoy_server_concurrency gauge
envoy_server_concurrency{} 4
# TYPE envoy_server_version gauge
envoy_server_version{} 15294198
# TYPE envoy_server_memory_allocated gauge
envoy_server_memory_allocated{} 3875056
# TYPE envoy_http_downstream_cx_rx_bytes_buffered gauge
envoy_http_downstream_cx_rx_bytes_buffered{envoy_http_conn_manager_prefix="admin"} 513
# TYPE envoy_access_log_file_write_total_buffered gauge
envoy_access_log_file_write_total_buffered{} 0
# TYPE envoy_listener_manager_total_listeners_warming gauge
envoy_listener_manager_total_listeners_warming{} 0
# TYPE envoy_http_downstream_cx_upgrades_active gauge
envoy_http_downstream_cx_upgrades_active{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_rq_active gauge
envoy_http_downstream_rq_active{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_runtime_num_keys gauge
envoy_runtime_num_keys{} 0
# TYPE envoy_http_downstream_cx_tx_bytes_buffered gauge
envoy_http_downstream_cx_tx_bytes_buffered{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_server_live gauge
envoy_server_live{} 1
# TYPE envoy_http_downstream_cx_ssl_active gauge
envoy_http_downstream_cx_ssl_active{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_http_downstream_cx_http2_active gauge
envoy_http_downstream_cx_http2_active{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_cluster_circuit_breakers_high_rq_retry_open gauge
envoy_cluster_circuit_breakers_high_rq_retry_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_max_host_weight gauge
envoy_cluster_max_host_weight{envoy_cluster_name="http_service"} 1
# TYPE envoy_cluster_circuit_breakers_default_cx_open gauge
envoy_cluster_circuit_breakers_default_cx_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_high_rq_open gauge
envoy_cluster_circuit_breakers_high_rq_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_default_rq_open gauge
envoy_cluster_circuit_breakers_default_rq_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_membership_healthy gauge
envoy_cluster_membership_healthy{envoy_cluster_name="http_service"} 2
# TYPE envoy_cluster_lb_subsets_active gauge
envoy_cluster_lb_subsets_active{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_default_rq_pending_open gauge
envoy_cluster_circuit_breakers_default_rq_pending_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_active gauge
envoy_cluster_upstream_cx_active{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_pending_active gauge
envoy_cluster_upstream_rq_pending_active{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_version gauge
envoy_cluster_version{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_tx_bytes_buffered gauge
envoy_cluster_upstream_cx_tx_bytes_buffered{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_membership_total gauge
envoy_cluster_membership_total{envoy_cluster_name="http_service"} 2
# TYPE envoy_cluster_circuit_breakers_default_rq_retry_open gauge
envoy_cluster_circuit_breakers_default_rq_retry_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_default_cx_pool_open gauge
envoy_cluster_circuit_breakers_default_cx_pool_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_high_rq_pending_open gauge
envoy_cluster_circuit_breakers_high_rq_pending_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_membership_degraded gauge
envoy_cluster_membership_degraded{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_high_cx_open gauge
envoy_cluster_circuit_breakers_high_cx_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_rq_active gauge
envoy_cluster_upstream_rq_active{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_circuit_breakers_high_cx_pool_open gauge
envoy_cluster_circuit_breakers_high_cx_pool_open{envoy_cluster_name="http_service"} 0
# TYPE envoy_cluster_upstream_cx_rx_bytes_buffered gauge
envoy_cluster_upstream_cx_rx_bytes_buffered{envoy_cluster_name="http_service"} 0
# TYPE envoy_listener_downstream_pre_cx_active gauge
envoy_listener_downstream_pre_cx_active{envoy_listener_address="0.0.0.0_9988"} 0
# TYPE envoy_listener_downstream_cx_active gauge
envoy_listener_downstream_cx_active{envoy_listener_address="0.0.0.0_9988"} 0
envoy_http_downstream_cx_upgrades_active{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_tx_bytes_buffered{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_active{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_http1_active{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_http2_active{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_rx_bytes_buffered{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_rq_active{envoy_http_conn_manager_prefix="ingress_http"} 0
envoy_http_downstream_cx_ssl_active{envoy_http_conn_manager_prefix="ingress_http"} 0
# TYPE envoy_listener_admin_downstream_cx_length_ms histogram
envoy_listener_admin_downstream_cx_length_ms_bucket{le="0.5"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="1"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="5"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="10"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="25"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="50"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="100"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="250"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="500"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="1000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="2500"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="5000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="10000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="30000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="60000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="300000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="600000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="1800000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="3600000"} 0
envoy_listener_admin_downstream_cx_length_ms_bucket{le="+Inf"} 0
envoy_listener_admin_downstream_cx_length_ms_sum{} 0
envoy_listener_admin_downstream_cx_length_ms_count{} 0
# TYPE envoy_http_downstream_rq_time histogram
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="0.5"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="1"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="5"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="10"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="25"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="50"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="100"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="250"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="500"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="1000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="2500"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="5000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="10000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="30000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="60000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="300000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="600000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="1800000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="3600000"} 1
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="admin",le="+Inf"} 1
envoy_http_downstream_rq_time_sum{envoy_http_conn_manager_prefix="admin"} 0
envoy_http_downstream_rq_time_count{envoy_http_conn_manager_prefix="admin"} 1
# TYPE envoy_http_downstream_cx_length_ms histogram
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="0.5"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="1"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="5"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="10"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="25"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="50"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="100"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="250"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="500"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="1000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="2500"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="5000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="10000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="30000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="60000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="300000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="600000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="1800000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="3600000"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="admin",le="+Inf"} 0
envoy_http_downstream_cx_length_ms_sum{envoy_http_conn_manager_prefix="admin"} 0
envoy_http_downstream_cx_length_ms_count{envoy_http_conn_manager_prefix="admin"} 0
# TYPE envoy_cluster_upstream_cx_connect_ms histogram
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="0.5"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="1"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="5"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="10"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="25"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="50"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="100"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="250"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="500"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="1000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="2500"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="5000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="10000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="30000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="60000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="300000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="600000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="1800000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="3600000"} 5
envoy_cluster_upstream_cx_connect_ms_bucket{envoy_cluster_name="http_service",le="+Inf"} 5
envoy_cluster_upstream_cx_connect_ms_sum{envoy_cluster_name="http_service"} 0
envoy_cluster_upstream_cx_connect_ms_count{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_cx_length_ms histogram
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="0.5"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="1"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="5"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="10"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="25"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="50"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="100"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="250"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="500"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="1000"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="2500"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="5000"} 0
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="10000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="30000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="60000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="300000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="600000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="1800000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="3600000"} 5
envoy_cluster_upstream_cx_length_ms_bucket{envoy_cluster_name="http_service",le="+Inf"} 5
envoy_cluster_upstream_cx_length_ms_sum{envoy_cluster_name="http_service"} 25250
envoy_cluster_upstream_cx_length_ms_count{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_external_upstream_rq_time histogram
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="0.5"} 1
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1"} 1
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="5"} 3
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="10"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="25"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="50"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="100"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="250"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="500"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="2500"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="5000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="10000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="30000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="60000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="300000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="600000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1800000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="3600000"} 5
envoy_cluster_external_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="+Inf"} 5
envoy_cluster_external_upstream_rq_time_sum{envoy_cluster_name="http_service"} 17.200000000000002842170943040401
envoy_cluster_external_upstream_rq_time_count{envoy_cluster_name="http_service"} 5
# TYPE envoy_cluster_upstream_rq_time histogram
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="0.5"} 1
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1"} 1
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="5"} 3
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="10"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="25"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="50"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="100"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="250"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="500"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="2500"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="5000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="10000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="30000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="60000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="300000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="600000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="1800000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="3600000"} 5
envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="http_service",le="+Inf"} 5
envoy_cluster_upstream_rq_time_sum{envoy_cluster_name="http_service"} 17.200000000000002842170943040401
envoy_cluster_upstream_rq_time_count{envoy_cluster_name="http_service"} 5
# TYPE envoy_listener_downstream_cx_length_ms histogram
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="0.5"} 0
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="1"} 0
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="5"} 3
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="10"} 4
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="25"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="50"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="100"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="250"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="500"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="1000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="2500"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="5000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="10000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="30000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="60000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="300000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="600000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="1800000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="3600000"} 5
envoy_listener_downstream_cx_length_ms_bucket{envoy_listener_address="0.0.0.0_9988",le="+Inf"} 5
envoy_listener_downstream_cx_length_ms_sum{envoy_listener_address="0.0.0.0_9988"} 28.6999999999999992894572642399
envoy_listener_downstream_cx_length_ms_count{envoy_listener_address="0.0.0.0_9988"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="0.5"} 0
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1"} 0
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="5"} 3
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="10"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="25"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="50"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="100"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="250"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="500"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="2500"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="5000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="10000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="30000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="60000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="300000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="600000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1800000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="3600000"} 5
envoy_http_downstream_rq_time_bucket{envoy_http_conn_manager_prefix="ingress_http",le="+Inf"} 5
envoy_http_downstream_rq_time_sum{envoy_http_conn_manager_prefix="ingress_http"} 19.25
envoy_http_downstream_rq_time_count{envoy_http_conn_manager_prefix="ingress_http"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="0.5"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1"} 0
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="5"} 3
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="10"} 4
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="25"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="50"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="100"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="250"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="500"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="2500"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="5000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="10000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="30000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="60000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="300000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="600000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="1800000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="3600000"} 5
envoy_http_downstream_cx_length_ms_bucket{envoy_http_conn_manager_prefix="ingress_http",le="+Inf"} 5
envoy_http_downstream_cx_length_ms_sum{envoy_http_conn_manager_prefix="ingress_http"} 28.6999999999999992894572642399
envoy_http_downstream_cx_length_ms_count{envoy_http_conn_manager_prefix="ingress_http"} 5

gRPC Notes

Mon, 06 May 2019 02:01:22 GMT

1. 前言
2. 基本资料及网络问题
3. 并发编程
4. 负载均衡
5. 状态检查
6. Interceptor
7. Debug
8. 监控
资料
- 链接

1. 前言

首先需要申明本文并不是通泛的对gRPC的讲解，而是以Golang为基础的一篇gRPC偏应用方向的博文。因此后面的所有技术点和使用范例都会以Go语言为基础。此外，本文中对gRPC偏基础方面的内容不会涉猎过多，而是更多讲解gRPC偏设计方向的技术点。

2. 基本资料及网络问题

2.1 Go support for Protocol Buffers

关于使用Go语言的情况下的一系列protobuf相关技术点，可以参阅：golang/protobuf。

主要需要关注的点有几个：

安装：除了标准的protobuf（protoc）之外，还需要安装go的插件：protoc-gen-go
插件：protoc如果要使用go的插件，且需要生成service相关代码的话，需要在go_out中附带上plugins=grpc:字符串，e.g：--go_out=plugins=grpc:${OUTPUT_PATH}
包管理：protobuf的包定义和go语言的习惯用法有不少差异，使用前建议阅读：Packages and input paths
- 默认的包名不会转换成相对文件夹，e.g：package com.book会生成com_book文件夹，而不是com/book这样的嵌套文件夹
- go的包路径可以使用：option go_package = ...来设定
- 在某些全局编译的情况下，可以：--go_out=$GOPATH，直接输出到GOPATH
生成出来的代码相关规范：Generated code
protoc插件的额外参数：Parameters

2.2 gRPC Basics: Go

初次使用Go语言来编写gRPC代码，请阅读文档：grpc-go/examples/gotutorial.md。

对于gRPC非常熟悉的程序员可以跳过这个文档，基本上这个文档是面向新手的指引，但是范例代码都使用的是Go语言。

2.3 gRPC enhanced example

进阶的Go语言gRPC代码可以阅读范例：grpc-go/examples/route_guide/。这个范例代码里加入了单向和双向流的范例，算是比较进阶和完整的范例代码了。

我的实验项目中也有比较完整的应用范例代码，相对官方的范例来说少了点不伦不类的业务逻辑，对于只需要了解技术的读者来说更友好：dist-system-practice/golang/src/experiment/grpc/samples/book/。

2.4 网络问题

因国情原因，Go的包安装会遇到一些网络问题：

这种情况的最佳对应方法是在命令行下设置HTTP和HTTPS代理：

export http_proxy=http://127.0.0.1:6152
export https_proxy=http://127.0.0.1:6152
go get -u ...

3. 并发编程

3.1 Go语言的gRPC并发

关于在Go语言中使用gRPC的并发问题在官方的issues中已经有很多了：

上述的三个issues都可以仔细阅读下，提出的问题都非常有代表性。从一系列的问题中可以看出，官方对于gRPC的并发其实是有一些指导意见的，但并没有很好的文档化（至少之前如此）。而目前对这些问题已经有部分解答了，请继续阅读下去。

3.2 并发相关官方文档 {#ID_CONCURRENCY_DOC}

在这个提交中，官方添加了对于并发相关的官方指引。正式的文档地址是在：grpc-go/Documentation/concurrency.md。

这里做下简单翻译：

Concurrency

一般来说，gRPC-go提供了对并发友好的API。下文是一些指引。

Clients

一个ClientConn可以被安全地并发访问。以helloworld作为范例，程序员可以在多个goroutine之间共享一个ClientConn来创建多个GreeterClient客户端类型。在这种使用情况下，RPCs会并行传输。

Streams

当使用Stream的时候，程序员必须小心避免从不同的goroutine向同一个stream发送多次SendMsg或RecvMsg请求。换句话来说，如果有一个goroutine向stream中发送SendMsg，然后在同一时间有另一个goroutine向stream中发送RecvMsg，这样做是安全的。但在不同的goroutine中同时向同一个stream发送SendMsg，或是RecvMsg则是不安全的。

Servers

每个被附到已注册服务器上的RPC处理器都会在其自身的goroutine中运作。举例来说，SayHello会在其自身的goroutine中被调用到。同样的，streaming RPC也是一样，route guide例子可以在这里看得到。

3.3 并发范例

我在实验项目中做了点并发的范例，可以看下：dist-system-practice/golang/src/experiment/grpc/samples/concurrency/。

3.3.1 代码差异

服务端代码是一致的，根据3.2 并发相关官方文档，服务端的所有请求都是自然并发的，无需代码特殊处理。但客户端则需要自行编码处理。

顺序执行：

for i := 1; i <= 10; i++ {
    start := time.Now()
    if response, err := client.Echo(ctx, &pb.EchoRequest{Id: int64(i)}); err != nil {
        log.Fatalf("[Client] singleConnSequence: err: %v", err)
    } else {
        end := time.Now()
        elapsed := end.Sub(start)
        log.Printf("[Client] singleConnSequence: response: %v, consumed: %v", response, elapsed)
    }
}

并发执行：

var waitgroup sync.WaitGroup

for i := 1; i <= 10; i++ {
    waitgroup.Add(1)
    go func(id int) {
        start := time.Now()
        if response, err := client.Echo(ctx, &pb.EchoRequest{Id: int64(id)}); err != nil {
            log.Fatalf("[Client] singleConnConcurrency: err: %v", err)
        } else {
            end := time.Now()
            elapsed := end.Sub(start)
            log.Printf("[Client] singleConnConcurrency: response: %v, consumed: %v", response, elapsed)
        }
        waitgroup.Done()
    }(i)
}
waitgroup.Wait()

3.3.2 顺序执行

# 启动服务器
DELAY_NO_5=true go run server.go

# 启动客户端，发送请求
MODE=CONN_ONE_SEQUENCE go run client.go

# 客户端输出
2019/05/03 13:58:23 [Client] singleConnSequence: response: id:1 , consumed: 4.284231ms
2019/05/03 13:58:23 [Client] singleConnSequence: response: id:2 , consumed: 381.818µs
2019/05/03 13:58:23 [Client] singleConnSequence: response: id:3 , consumed: 361.608µs
2019/05/03 13:58:23 [Client] singleConnSequence: response: id:4 , consumed: 332.662µs
2019/05/03 13:58:24 [Client] singleConnSequence: response: id:5 , consumed: 1.004485058s
2019/05/03 13:58:24 [Client] singleConnSequence: response: id:6 , consumed: 470.532µs
2019/05/03 13:58:24 [Client] singleConnSequence: response: id:7 , consumed: 468.148µs
2019/05/03 13:58:24 [Client] singleConnSequence: response: id:8 , consumed: 389.214µs
2019/05/03 13:58:24 [Client] singleConnSequence: response: id:9 , consumed: 418.01µs
2019/05/03 13:58:25 [Client] singleConnSequence: response: id:10 , consumed: 1.003602442s

# 服务器输出
2019/05/03 13:58:23 [Server] Echo: request: id:1
2019/05/03 13:58:23 [Server] Echo: response: id:1
2019/05/03 13:58:23 [Server] Echo: request: id:2
2019/05/03 13:58:23 [Server] Echo: response: id:2
2019/05/03 13:58:23 [Server] Echo: request: id:3
2019/05/03 13:58:23 [Server] Echo: response: id:3
2019/05/03 13:58:23 [Server] Echo: request: id:4
2019/05/03 13:58:23 [Server] Echo: response: id:4
2019/05/03 13:58:23 [Server] Echo: request: id:5
2019/05/03 13:58:24 [Server] Echo: response: id:5
2019/05/03 13:58:24 [Server] Echo: request: id:6
2019/05/03 13:58:24 [Server] Echo: response: id:6
2019/05/03 13:58:24 [Server] Echo: request: id:7
2019/05/03 13:58:24 [Server] Echo: response: id:7
2019/05/03 13:58:24 [Server] Echo: request: id:8
2019/05/03 13:58:24 [Server] Echo: response: id:8
2019/05/03 13:58:24 [Server] Echo: request: id:9
2019/05/03 13:58:24 [Server] Echo: response: id:9
2019/05/03 13:58:24 [Server] Echo: request: id:10
2019/05/03 13:58:25 [Server] Echo: response: id:10

3.3.3 并发执行

# 启动服务器
DELAY_NO_5=true go run server.go

# 启动客户端，发送请求
MODE=CONN_ONE_CONCURRENCY go run client.go

# 客户端输出
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:9 , consumed: 5.651184ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:6 , consumed: 5.595945ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:2 , consumed: 5.693124ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:4 , consumed: 5.637734ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:1 , consumed: 5.592096ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:3 , consumed: 5.58596ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:7 , consumed: 5.652258ms
2019/05/03 13:54:41 [Client] singleConnConcurrency: response: id:8 , consumed: 5.658945ms
2019/05/03 13:54:42 [Client] singleConnConcurrency: response: id:10 , consumed: 1.008472004s
2019/05/03 13:54:42 [Client] singleConnConcurrency: response: id:5 , consumed: 1.008440948s

# 服务器输出
2019/05/03 13:54:41 [Server] Echo: request: id:3
2019/05/03 13:54:41 [Server] Echo: response: id:3
2019/05/03 13:54:41 [Server] Echo: request: id:1
2019/05/03 13:54:41 [Server] Echo: response: id:1
2019/05/03 13:54:41 [Server] Echo: request: id:6
2019/05/03 13:54:41 [Server] Echo: response: id:6
2019/05/03 13:54:41 [Server] Echo: request: id:10
2019/05/03 13:54:41 [Server] Echo: request: id:8
2019/05/03 13:54:41 [Server] Echo: response: id:8
2019/05/03 13:54:41 [Server] Echo: request: id:9
2019/05/03 13:54:41 [Server] Echo: response: id:9
2019/05/03 13:54:41 [Server] Echo: request: id:5
2019/05/03 13:54:41 [Server] Echo: request: id:2
2019/05/03 13:54:41 [Server] Echo: response: id:2
2019/05/03 13:54:41 [Server] Echo: request: id:4
2019/05/03 13:54:41 [Server] Echo: response: id:4
2019/05/03 13:54:41 [Server] Echo: request: id:7
2019/05/03 13:54:41 [Server] Echo: response: id:7
2019/05/03 13:54:42 [Server] Echo: response: id:10
2019/05/03 13:54:42 [Server] Echo: response: id:5

服务端对ID逢5的请求sleep 1秒进行反馈，因此并发的客户端请求中，5和10就是最后返回打印出来的，耗时也是1秒多。

3.4 连接池

虽然单连接也是可以进行并发编程的，但在某些极端情况下，数据包可能达到网络吞吐的极限。众所周知Go语言天生对并发编程友好，因此CPU的利用必然是非常充分的，如果RPC服务的类型是低CPU消耗而高网络消耗的情况就有可能出现之前提到的问题。这种情况就需要创建多个连接了。

在多连接管理方面，官方的类库并没有连接池的功能，第三方倒是有：grpc-go-pool/pool_test.go。

此外，可以拓展阅读：Pooling gRPC Connections。

范例可以看：dist-system-practice/golang/src/experiment/grpc/samples/pool/。

3.5 Benchmark

范例代码在：dist-system-practice/golang/src/experiment/grpc/samples/throughput/。

测试硬件

rMBP 2014 mid
CPU：2.5GHz 四核 Intel Core i7 处理器 (Turbo Boost 3.7GHz)

测试的时候一些在系统使用中的软件我并没有清空，因此可能有稍许干扰，但总体问题不大。

客户端及服务器启动命令

CORE_NUM=3 go run server.go
CORE_NUM=4 ROUTINES_PER_CORE=50 go run client.go

使用CORE_NUM来控制使用到的物理核心数量，客户端使用ROUTINES_PER_CORE来决定启动的routine总量：CORE_NUM * ROUTINES_PER_CORE。

测试结果

请求数量/s：

2019/05/04 14:19:33 [Client] 73065 requests in 1s
2019/05/04 14:19:34 [Client] 68826 requests in 1s
2019/05/04 14:19:35 [Client] 73655 requests in 1s
2019/05/04 14:19:36 [Client] 70973 requests in 1s
2019/05/04 14:19:37 [Client] 73645 requests in 1s
2019/05/04 14:19:38 [Client] 70616 requests in 1s
2019/05/04 14:19:39 [Client] 72252 requests in 1s
2019/05/04 14:19:40 [Client] 69342 requests in 1s
2019/05/04 14:19:41 [Client] 69745 requests in 1s
2019/05/04 14:19:42 [Client] 62251 requests in 1s
2019/05/04 14:19:43 [Client] 58043 requests in 1s
2019/05/04 14:19:44 [Client] 69316 requests in 1s
2019/05/04 14:19:45 [Client] 69796 requests in 1s
2019/05/04 14:19:46 [Client] 57246 requests in 1s
2019/05/04 14:19:47 [Client] 72265 requests in 1s
2019/05/04 14:19:48 [Client] 72940 requests in 1s
2019/05/04 14:19:49 [Client] 70237 requests in 1s

CPU：

Network：

结论

因硬件环境的限制，没有使用通过网卡的测试方案，而是使用了127.0.0.1的环回请求方案。此外，测试期间MAC上的一些软件进程也并没有进行清理，因此可能有部分干扰。结论就不做了，这样简单且限制资源的benchmark实际意义不大，列几点可以观测到的状态：

请求数量/s符合预期
CPU占用基本满
提升核心使用数量，提升routine数量，能观察到rps提升

4. 负载均衡

官方有一篇关于负载均衡设计的文档，可以读下：Load Balancing in gRPC。

意义不大，可以了解一些简单的负载均衡概念，以及一些设计上的思路。

5. 状态检查

官方对于如何设计及暴露服务端状态检查接口的一份文档：GRPC Health Checking Protocol。可以说是一份guideline。同样意义不大。

6. Interceptor

所谓的interceptor，写过gin或者koa的可以直接理解为gRPC里的middleware。官方文档：Interceptor。

虽然gRPC本身的rpc调用分为多种不同的可能：

请求响应皆为unary
请求unary响应stream
请求stream响应unary
请求响应皆为stream

但interceptor的签名则只有unary和stream这两种。

范例代码可以查看官方的：

在使用中可能会遇到多个Interceptor同时存在的情况，在编码的时候就需要使用工具对其进行组合：go-grpc-middleware/chain.go：

s := grpc.NewServer(
	grpc_middleware.WithUnaryServerChain(
		grpc_opentracing.UnaryServerInterceptor(),
		grpc_prometheus.UnaryServerInterceptor,
	),
	grpc.StreamInterceptor(grpc_prometheus.StreamServerInterceptor),
)

7. Debug

官方的指引：Debugging，包括了一份范例代码：

也可以使用go的trace包，做简单的观察：Golang gRPC实践连载六内置Trace。

几个环境变量可以大量输出程序执行的细节：

GODEBUG=http2debug=1 \
GODEBUG=http2debug=2 \
GRPC_GO_LOG_VERBOSITY_LEVEL=99 \
GRPC_GO_LOG_SEVERITY_LEVEL=info \
yourapp

8. 监控

Grpc go自身也有监控用的Interceptor：grpc-ecosystem/go-grpc-prometheus，和HTTP服务器无关，主要是grpc自身的指标。

范例代码可以参见README中的说明，服务端和客户端代码都有提供。

资料

链接

Kafka Notes

Mon, 29 Apr 2019 02:01:22 GMT

1. 前言
2. 消息队列
3. 消息队列选型比较
- 3.1 Apache Pulsar
4. Kafka架构
5. Kafka监控 & 高可用
- 5.1 监控
  - 5.1.1 Exporter & Grafana Dashboard
  - 5.1.2 Docker实践
- 5.2 高可用
6. Kafka Benchmark
7. Kafka使用范例
8. 在Docker内部署集群
9. 写性能与安全性
10. TODO
资料
- 链接

1. 前言

Kafka是现在业界选择比较多的一种消息队列解决方案。我这里主要也是选Kafka作为消息队列这块需求的解决方案。下面的技术调研会先从消息队列本身开始，然后做一个横向比较，最后再聚焦到Kafka本身上。

调研用的Kafka版本为：

2.2.0

官方文档：

官方介绍：Introduction
官方新手入门：Quickstart
官方应用场景介绍：Use cases
官方文档：Documentation
Docker Hub：wurstmeister/kafka

一本中文手册，版本较老，看看范例代码尚可：Apache kafka中文手册。

2. 消息队列

在聊Kafka之前，其实更需要关注下消息队列本身。什么需求下需要使用消息队列、消息队列的功能点有哪些、消息队列的模式有哪些、消息队列的实现难点有哪些，等等。如果什么都不了解，那技术选型就无从谈起了，也没办法理解为什么消息队列要做好是非常困难的一件事情。展开了说，也就没办法举一反三，理解其他软件系统的设计精髓了。

下面会简单列举下消息队列的一系列知识点，细节内容这里就不展开了，篇幅太大。

消息队列的需求：

解耦
最终一致性
广播
错峰与流控

消息队列的模型：

点对点：单生产、单队列、单消费
生产者消费者模型：多生产、单队列、多消费
发布订阅模型：根据topic分队列，多生产、多队列、多消费

消息队列的投递模式：

Push：消息队列主动推送（e.g RocketMQ可选）
Pull：消费者主动抓取（e.g Kafka）

消息队列的性能指标：

吞吐量（Throughput）
响应时间（Latency）

消息队列的投递策略：

最多一次（At most Once）：消息可能会丢，但绝不会重复传输
最少一次（At least Once）：消息绝不会丢，但可能会重复传输
仅有一次（Exactly Once）：每条消息肯定会被传输一次且仅传输一次

消息队列的功能性：

优先级队列
延迟队列
死信队列
重试队列
消息回溯
消息堆积 + 持久化
消息追踪
消息过滤
多租户
多协议支持
跨语言支持
流量控制
可靠投递
消费确认
消息顺序性
安全机制
消息幂等性
事务性消息

几篇值得一读的博文：

消息队列设计精要 - 美团点评技术团队

一篇通论形式的消息队列设计博文，讲解了一些消息队列通用的知识点，值得一读。

分布式队列编程：从模型、实战到优化

本质上也是一篇对于消息队列进行设计和讲解的博文，但结合了美团公司内部的实际项目经验，对于大型系统的设计者有更好的贴近应用场景的指导作用。

分布式队列编程优化篇

接上一篇的博文，更多讲到了性能和高级功能相关的实现以及性能的优化。

如何保证消息队列的高可用和幂等性以及数据丢失，顺序一致性

排版比较粗糙，但内容非常不错。以贴近项目经验的内容讲解了RabbitMQ和Kafka的：

高可用性
消息幂等性
消息可靠性
消息顺序性
消息积压场景处理

3. 消息队列选型比较

消息队列的选型一直都是比较困难的，业界现在比较主流的选择有：ActiveMQ、RabbitMQ、Kafka、RocketMQ、ZeroMQ 这几种。

有几篇不错的博文可以看下：

消息中间件选型分析：从 Kafka 与 RabbitMQ 的对比看全局

这篇时间还算比较接近2018年5月2日，主要是以Kafka和RabbitMQ为范例进行了消息队列选型的要点讲解。虽然讲解的时候使用了Kafka以及RabbitMQ作为范例，但实际上讲解的是通用的消息队列选型要点。结合本文上一节所讲到的消息队列的一系列知识点，应该能有更深刻的理解。

滴滴出行基于 RocketMQ 构建企业级消息队列服务的实践

这篇时间稍微有点久，文中提到的Kafka版本还是0.8左右的（虽然文章的发布时间倒是不久之前），所以文中提到的性能指标之类的仅可作为参考。这篇文章是对Kafka和RocketMQ做的一个技术选型比较，文章中有相当多的性能指标比较，并结合滴滴公司的实际情况讲解了下消息队列系统进行替换时候所做的Migration工作，非常有借鉴价值。此外，文中还有一小节讲解了下RocketMQ使用的经验。

Why is Kafka pull-based instead of push-based?

为什么Kafka消息队列使用的是Pull投递模式。

Modern Open Source Messaging: NATS, RabbitMQ, Apache Kafka, hmbdc, Synapse, NSQ and Pulsar

老外写的一篇，提到了不少国内较少提到的开源项目，可以作为参考。

3.1 Apache Pulsar

关于Kafka和后起新秀Pulsar的横向比较，可以看：

大略的要点：

功能性上Pulsar要比Kafka更好，且这是在不牺牲性能的前提下的，就更加难能可贵
解决了Kafka单partition只能单consumer消费的问题
将Broker和存储解耦，做到更好的错误恢复，在Broker宕机之后可以做到无损耗恢复
存储方面的功能交付给Bookie，更细粒度的存储，更好的错误恢复和同步性能

4. Kafka架构

4.1 概念

老样子从基本的概念开始梳理：

broker：kafka集群中的任意一台提供服务的物理服务器即被称为broker
topic：消息队列的一个队列，一般做架构的时候按需求将不同的消息分别派送到不同的管道里，而其中的任意一个管道在kafka里就是一个topic
partition：topic下的概念，任意一个topic根据启动时的设定，会分成多个partition，而每个partition会由集群安排在某一台物理机broker上，以此做到集群的横向扩展
offset：partition下的概念，topic被分为很多partition，而每个partition则都会存储消息，每个partition存储的消息都是从0开始进行标号，而这个每条消息一个的标号，即为offset；可以理解为消息在partition里的唯一id；不同的partition都是从0开始标号，因此offset只对其自身的partition生效，不可混用
replica：某个partition的完整备份（在接收写入请求时数据可能会落后于leader），用在集群的高可用服务上，同时也可以提供partition读操作的负载均衡
producer：向topic里输入消息数据的角色
consumer：从topic里消费消息数据的角色
consumer group：可扩展且具有容错性的consumer机制，多个consumer共享一个group id，组内的所有consumer一起来消费topic的所有partition；但一个partition仍旧只能由一个consumer进行消费；主要是为了解决consumer和partition配对balance的问题，将consumer做成组由集群自动进行平衡并分配到partition

关于consumer group，更多的可以看：Kafka消费组(consumer group)。

4.2 集群 {#ID_CLUSTER}

一张图基本上就能说明问题：

kafka集群由多台broker（物理机）组成
图示中有四台broker
每个topic会根据配置，生成固定数量的partition，均匀分配到物理机上
图示中的topic被分成了3个partition：P1_leader（broker1）、P2_leader（broker2）、P3_leader（broker4）
每个partition根据配置，会拥有固定数量的follower（replica），分别分配到各个物理机上
图示中即：P1_follower（broker2、broker3）、P2_follower（broker3、broker4）、P3_follower（broker1、broker2）
当有broker宕机的时候：
- 丢失的follower会由集群重新寻找节点进行备份恢复
- 丢失的leader会由集群自现存的follower中选举产生，成为新的leader

4.3 分布式痛点（offset）

Kafka在分布式解决方案上也有痛点，主要是每个partition的offset问题。

为了性能，kafka将一个partition视作一个管道，拥有一个从0开始的offset。这样做的好处就是不再需要在每一个消息体上做metadata存放该消息是否被消费掉等信息，而是通过partition的offset来标记整个管道中的消息被消费到了哪里。消息体更简单，流程上也更简单，不会出现乱序的消费情况。但也正是因为这种设计，导致每个partition无法由多个consumer并发消费，每个partition绑定只能同时允许一个consumer消费。

因此，从机制上来说，kafka并不适合用来做consumer重消耗（CPU）类型的消息通道。虽然partition可以做很多，极端点来说可以做到和consumer实际需求1：1的配比，但超过适配当前需求的partition数量设置也会造成吞吐量的下降（参见：6.2.4 场景4）。

consumer和partition在进行消息是否被消费掉的确认行为上，有两种方式：

自动提交：
- 设置enable.auto.commit=true
- 更新的频率根据参数auto.commit.interval.ms来定，这种方式被称为at most once
- consumer fetch到消息后，partition就会更新offset，无论是否消费成功
手动提交：
- 设置enable.auto.commit=false
- 这种方式被称为at least once
- consumer fetch到消息后，必须在消费成功后调用方法consumer.commitSync()，手动通知partition更新offset
- 如果消费失败，则offset不会更新，此条消息会被重复消费一次

关于partition和consumer之间的关系，更多可以看下：

How multiple consumer group consumers work across partition on the same topic in Kafka?

kafka中partition和消费者对应关系

以及自动提交相关：Understanding the ‘enable.auto.commit’ Kafka Consumer property。

4.4 临时消费压力应急

如果因某些原因，之前设计的partition分片数量不够导致能够上工的consumer数量不够，且consumer的消费速率跟不上的时候，就会发生消息堆积。如果堆积的情况比较严重的话，就需要程序介入处理。

思路如下：

老的partition以及老的topic肯定不能动，就算重新进行repartition整个集群重新平衡耗费的时间也是难以忍受的
创建新的topic
将新的topic的partition设到consumer消费速率能跟上的数量
将新的consumer部署上去，消费新设置的topic和partition
将老的topic以及partition上挂载的consumer全部停止
在老的topic以及partition上挂载临时consumer，这批consumer不做任何逻辑处理，只是将老的topic内的消息全部读取出来，并输入到新的topic里

这样老的topic里的消息就全部分发到新的topic里了，且新的topic的partition数量很高，可以挂载很多consumer处理堆积的消息。

5. Kafka监控 & 高可用

5.1 监控

监控方面，datadog的几篇文章非常不错，值得一读，不过版本有点老了，文章是2016年的：

详细的指标列表及其含义，可以看这篇：Monitoring Kafka。

5.1.1 Exporter & Grafana Dashboard

Prometheus的Exporter分为两块：

以Java为runtime的通用监控：prometheus/jmx_exporter
- 代码：prometheus/jmx_exporter
- 镜像：sscaling/jmx-prometheus-exporter
  - sscaling/jmx-prometheus-exporter:0.11.0
- Dashboard：
  - Kafka Overview，这个dashboard相当老了，一直没有更新，而且仅只有6个Panel，和kafka有关的panel更只有3个，基本没什么用；但未能找到更近一点的kafka专用dashboard
  - JVM dashboard，jmx通用dashboard，看上去更好点；但这个dashboard变量设置的是job，所以在设置Prometheus的时候就需要将多个kafka的数据采集到同一个job里，而不是分开
  - JMX exporter prometheus，另一款jmx通用dashboard；这个dashboard是为了在k8s中使用而特化的，也不够灵活
列在Prometheus官方列表上的第三方Exporter：danielqsj/kafka_exporter
- 代码：danielqsj/kafka_exporter
- 镜像：danielqsj/kafka-exporter
  - danielqsj/kafka-exporter:v1.2.0
- Dashboard：Kafka Exporter Overview
- 该Exporter使用Golang编写，更专注于部分Kafka业务相关metrics，对于核心的Java runtime metrics仍旧需要jmx_exporter

此外，还有一个confluent公司的grafana dashboard配置，没找到对应的labs dashboard地址，但该配置文件本身也有参考价值：kafka-confluent-platform/grafana-kafka-dashboard.json。

可参考的jmx_exporter配置：

5.1.2 Docker实践

实际运行范例参见：

Exporter方面，jmx_exporter和kafka_exporter同时使用，两者侧重不同。jmx_exporter主要用来进行JVM监控，针对java runtime自身的状态进行监控，而kafka_exporter则针对kafka运行状况进行监控（其实只要不怕麻烦自己处理dashboard，则jmx_exporter就完全足够了）。

jmx_exporter的部署有两种选择，一是独立的容器进行部署，好处是可观察性强，且不会对kafka容器造成影响，缺点是部署更繁杂，配置内容更多；二是修改kafka容器，添加几项配置项，就可以直接在kafka容器内启动一个java进程，进行metrics输出。这里实践使用的是第二种方法，配置修改如下：

  kafka_1:
    image: ...
    ...
    volumes:
      - /private/tmp/jmx_prometheus_javaagent-0.9.jar:/usr/local/bin/jmx_prometheus_javaagent-0.9.jar
      - /private/tmp/jmx-kafka-2_0_0.yaml:/etc/jmx-exporter/jmx-kafka-2_0_0.yaml
      - ...
    networks:
      ...
    ports:
      - "19092:9092" # client port
      - "17071:7071" # jmx prometheus metrics
    expose:
      - "9092" # client port
      - "9093" # internal traffic
      - "9991" # jmx
      - "7071" # jmx prometheus metrics
    restart: "always"
    logging:
      <<: *KAFKA_LOGGING_DEFAULTS
    environment:
      ...
      JMX_PORT: 9991
      KAFKA_OPTS: "-javaagent:/usr/local/bin/jmx_prometheus_javaagent-0.9.jar=7071:/etc/jmx-exporter/jmx-kafka-2_0_0.yaml"
      <<: *KAFKA_ENV_DEFAULTS

JMX_PORT告知kafka在启动的时候需要一并启动jmx，KAFKA_OPTS告知kafka在启动时一并需要启动jmx_exporter，而这个exporter的jar包以及配置文件则是通过bind mount放入容器内的。

配置文件主要来自于：kafka-grafana/jmx-exporter/kafka-2_0_0.yml。此外，因为使用通用jmx dashboard：JVM dashboard来进行数据展示，该配置文件中也放入了部分这个dashboard要求的数据转换规则：

lowercaseOutputLabelNames: true

rules:
# JMX common
- pattern: 'java.lang<type=OperatingSystem><>(committed_virtual_memory|free_physical_memory|free_swap_space|total_physical_memory|total_swap_space)_size:'
  name: os_$1_bytes
  type: GAUGE
  attrNameSnakeCase: true
- pattern: 'java.lang<type=OperatingSystem><>((?!process_cpu_time)\w+):'
  name: os_$1
  type: GAUGE
  attrNameSnakeCase: true
...

此外还有prometheus集群采集添加以及grafana dashboard导入，都是常规操作，就不多说了。

5.2 高可用

在之前的4.2 集群中，已经介绍过了Kafka的集群模式，可以看到Kafka天然就是分布式的，而且在设计之初就考虑到了集群的高可用。本文之前章节内关于集群的内容偏简单了，只介绍了大致的设计。如有需要更深入了解分布式和高可用的细节，则可以阅读唯品会的：Kafka 数据可靠性深度解读，这篇讲解非常透彻，基本上可以当经典来看了。

Kafka的高可用配置，有几个配置项控制了集群的安全程度。这里需要记住一点，整个集群越安全集群的吞吐量就越低，这是等价交换的，不可能不付出任何代价就获得数据的安全性。唯品会的文章讲解的细节非常多，但我们真正执行操作的时候可以只知其然，懂得哪几个配置项需要操作即可：

topic：
- replication.factor：每个partition会拥有多少个replica
- min.insync.replicas：partition的leader节点要求当前在线的replica节点的数量，如果实际在线数量少于这个数值，客户端的请求会被拒绝：org.apache.kafka.common.errors.NotEnoughReplicasExceptoin: Messages are rejected since there are fewer in-sync replicas than required
broker：
- unclean.leader.election.enable：是否允许out-of-sync replica成为leader
producer：
- producer.type：消息生产者提交消息到kafka服务器的时候的模式，可选：sync或async
  - sync拥有很好的安全性
  - async拥有更高的吞吐量，可以批量进行消息发送
- request.required.acks：kafka服务器在收到消息之后何时对生产者进行完成反馈
  - 1（默认）：partition的leader节点收取完成即反馈，如果在follower同步数据之前leader宕机则数据丢失
  - 0：producer不等待kafka服务器反馈即直接进行后续发送，拥有最高的吞吐量以及最低的安全性
  - -1：partition的所有节点包括了leader以及所有的follower全部都确认数据同步完成再反馈，最高的安全性以及最低的吞吐量

要保证数据写入到Kafka是安全的，高可靠的，需要如下配置：

topic：
- replication.factor>=3：即副本数至少是3个
- 2<=min.insync.replicas<=replication.factor：要求每个partition leader的在线replica数量最少保持2个
broker：
- unclean.leader.election.enable=false：不允许out-of-sync replica成为leader
producer：
- request.required.acks=-1(all)：producer发送的消息请求必须让partition所有的replica都同步完毕才会返回成功
- producer.type=sync：producer发送的消息以同步方式发送，即在写入成功之前，producer必须等待

6. Kafka Benchmark

这里的内容全部是转载自唯品会的：Kafka 数据可靠性深度解读。网上的资料很容易失效，因此在这里做下转载。

Benchmark的Kafka版本是：

0.10.1.0

6.1 测试环境

Kafka broker 用到了 4 台机器，分别为 broker[0/1/2/3] 配置如下：

CPU: 24core/2.6GHZ
Memory: 62G
Network: 4000Mb
OS/kernel: CentOs release 6.6 (Final)
Disk: 1089G
Kafka 版本：0.10.1.0

broker 端 JVM 参数设置：

-Xmx8G -Xms8G -server -XX:+UseParNewGC -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -XX:+CMSScavengeBeforeRemark -XX:+DisableExplicitGC -Djava.awt.headless=true -Xloggc:/apps/service/kafka/bin/../logs/kafkaServer-gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=9999

客户端机器配置：

CPU: 24core/2.6GHZ
Memory: 3G
Network: 1000Mb
OS/kernel: CentOs release 6.3 (Final)
Disk: 240G

6.2 不同场景测试

6.2.1 场景1

测试不同的副本数、min.insync.replicas 策略以及 request.required.acks 策略（以下简称 acks 策略）对于发送速度（TPS）的影响。

具体配置：

一个 producer
发送方式为 sync
消息体大小为 1kB
partition 数为 12
副本数为：1/2/4
min.insync.replicas 分别为 1/2/4
acks 分别为 -1（all）/1/0

具体测试数据如下表（min.insync.replicas 只在 acks=-1 时有效）：

测试结果分析：

客户端的 acks 策略对发送的 TPS 有较大的影响，TPS：acks_0 > acks_1 > ack_-1;
副本数越高，TPS 越低；副本数一致时，min.insync.replicas 不影响 TPS；
acks=0/1 时，TPS 与 min.insync.replicas 参数以及副本数无关，仅受 acks 策略的影响。

下面将 partition 的个数设置为 1，来进一步确认下不同的 acks 策略、不同的 min.insync.replicas 策略以及不同的副本数对于发送速度的影响，详细请看情景 2 和情景 3。

6.2.2 场景2

在 partition 个数固定为 1，测试不同的副本数和 min.insync.replicas 策略对发送速度的影响。

具体配置：

一个 producer
发送方式为 sync
消息体大小为 1kB
producer 端 acks=-1(all)
变换副本数：2/3/4
min.insync.replicas 设置为：1/2/4

测试结果如下：

测试结果分析：

副本数越高，TPS 越低（这点与场景 1 的测试结论吻合），但是当 partition 数为 1 时差距甚微。min.insync.replicas 不影响 TPS。

6.2.3 场景3

在 partition 个数固定为 1，测试不同的 acks 策略和副本数对发送速度的影响。

具体配置：

一个 producer
发送方式为 sync
消息体大小为 1kB
min.insync.replicas=1
topic 副本数为：1/2/4
acks： 0/1/-1

测试结果如下：

测试结果分析（与情景 1 一致）：

副本数越多，TPS 越低；
客户端的 acks 策略对发送的 TPS 有较大的影响，TPS：acks_0 > acks_1 > ack_-1。

6.2.4 场景4 {#ID_BENCHMARK_SCEN4}

测试不同 partition 数对发送速率的影响

具体配置：

一个 producer
消息体大小为 1KB
发送方式为 sync
topic 副本数为 2
min.insync.replicas=2
acks=-1
partition 数量设置为 1/2/4/8/12

测试结果：

测试结果分析：

partition 的不同会影响 TPS，随着 partition 的个数的增长 TPS 会有所增长，但并不是一直成正比关系，到达一定临界值时，partition 数量的增加反而会使 TPS 略微降低。

6.2.5 场景5

通过将集群中部分 broker 设置成不可服务状态，测试对客户端以及消息落盘的影响。

具体配置：

一个 producer
消息体大小 1KB
发送方式为 sync
topic 副本数为 4
min.insync.replicas 设置为 2
acks=-1
retries=0/100000000
partition 数为 12

具体测试数据如下表：

出错信息：

错误 1：客户端返回异常，部分数据可落盘，部分失败：org.apache.kafka.common.errors.NetworkException: The server disconnected before a response was received.
错误 2：[WARN]internals.Sender - Got error produce response with correlation id 19369 on topic-partition default_channel_replicas_4_1-3, retrying (999999999 attempts left). Error: NETWORK_EXCEPTION
错误 3： [WARN]internals.Sender - Got error produce response with correlation id 77890 on topic-partition default_channel_replicas_4_1-8, retrying (999999859 attempts left). Error: NOT_ENOUGH_REPLICAS
错误 4： [WARN]internals.Sender - Got error produce response with correlation id 77705 on topic-partition default_channel_replicas_4_1-3, retrying (999999999 attempts left). Error: NOT_ENOUGH_REPLICAS_AFTER_APPEND

测试结果分析：

kill 两台 broker 后，客户端可以继续发送。broker 减少后，partition 的 leader 分布在剩余的两台 broker 上，造成了 TPS 的减小；
kill 三台 broker 后，客户端无法继续发送。Kafka 的自动重试功能开始起作用，当大于等于 min.insync.replicas 数量的 broker 恢复后，可以继续发送；
当 retries 不为 0 时，消息有重复落盘；客户端成功返回的消息都成功落盘，异常时部分消息可以落盘。

6.2.6 场景6

测试单个 producer 的发送延迟，以及端到端的延迟。

具体配置：

一个 producer
消息体大小 1KB
发送方式为 sync
topic 副本数为 4
min.insync.replicas 设置为 2
acks=-1
partition 数为 12

测试数据及结果（单位为 ms）：

6.3 各场景测试总结

当 acks=-1 时，Kafka 发送端的 TPS 受限于 topic 的副本数量（ISR 中），副本越多 TPS 越低；
acks=0 时，TPS 最高，其次为 1，最差为 -1，即 TPS：acks_0 > acks_1 > ack_-1；
min.insync.replicas 参数不影响 TPS；
partition 的不同会影响 TPS，随着 partition 的个数的增长 TPS 会有所增长，但并不是一直成正比关系，到达一定临界值时，partition 数量的增加反而会使 TPS 略微降低；
Kafka 在 acks=-1,min.insync.replicas>=1 时，具有高可靠性，所有成功返回的消息都可以落盘。

7. Kafka使用范例

实验使用的还是下载下来的Kafka，版本如头部申明的是2.2.0。范例代码可以在Github查看：dist-system-practice/experiment/kafka/。

8. 在Docker内部署集群

一般来说部署一个以上的docker容器组成集群，可以使用bash脚本的方法，自己编写命令一个个启动，但更好的方法是使用docker-compose命令，读取配置文件，将整个集群按设定的模式启动起来。可运行范例可以查看：dist-system-practice/conf/dev/kafka-cluster.yaml。

启动脚本：dist-system-practice/bash/dev/docker_kafka.sh。

主要有几个点需要注意下。

8.1 重要配置项

services:
  kafka_1:
    image: "wurstmeister/kafka:2.12-2.2.0" # 一定需要
    hostname: "kafka_1"
    container_name: "kafka_1" # 使用这个名字来让同network的其他服务进行访问
    depends_on:
      - "zookeeper" # 保证启动先后顺序
    volumes:
      - /private/tmp/jmx_prometheus_javaagent-0.9.jar:/usr/local/bin/jmx_prometheus_javaagent-0.9.jar
      - /private/tmp/jmx-kafka-2_0_0.yaml:/etc/jmx-exporter/jmx-kafka-2_0_0.yaml
      - kafka_vol_1:/tmp/kafka/data
    networks:
      - "net"
    ports:
      - "19092:9092" # client port # 保证非同一network的其他服务也能访问，但这么做要求每个kafka service都监听不同的端口，相互不能冲突
      - "17071:7071" # jmx prometheus metrics
    expose:
      - "9092" # client port
      - "9093" # internal traffic # kafka集群内部流量走的端口号
      - "9991" # jmx # jmx进程本身监听的地址，提供给jmx_exporter连接用
      - "7071" # jmx prometheus metrics # jmx_exporter监听的地址，提供给prometheus抓取metrics
    restart: "always"
    logging:
      driver: "json-file" # 日志输出以json格式，容易让聚合工具使用
      options:
        max-size: "512m" # 保证日志最大尺寸不会过大占用过多系统磁盘
    environment:
      KAFKA_LISTENERS: "INSIDE://0.0.0.0:9093,OUTSIDE://0.0.0.0:9092" # kafka的实际监听地址，一般不是0.0.0.0就是容器名
      KAFKA_ADVERTISED_LISTENERS: "INSIDE://kafka_1:9093,OUTSIDE://127.0.0.1:19092" # kafka发布到zookeeper，让客户端获取并凭之连接kafka的地址，一定需要是客户端能访问到的地址，INSIDE部分供集群内部流量使用，OUTSIDE供客户端使用
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT" # 明确内部外部的通讯协议
      KAFKA_INTER_BROKER_LISTENER_NAME: INSIDE # 告诉kafka集群上面的INSIDE和OUTSIDE配置哪个才是供集群内部流量使用的，按语义一般是INSIDE
      KAFKA_BROKER_ID: 0 # 必须每个kafka broker单独一个，不可重复
      JMX_PORT: 9991 # jmx监听的地址
      KAFKA_OPTS: "-javaagent:/usr/local/bin/jmx_prometheus_javaagent-0.9.jar=7071:/etc/jmx-exporter/jmx-kafka-2_0_0.yaml" # kafka在启动时一并会给予启动
      KAFKA_ZOOKEEPER_CONNECT: "zookeeper:2181" # 告知kafka zookeeper的地址
      KAFKA_LOG_DIRS: "/tmp/kafka-logs" # kafka实际的数据存放位置，推荐使用volume进行该地址的local映射
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3 # kafka内部用来保存topic的offset的数据，其replication数量
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1 # kafka内部用来保存transaction state log的数据，其replication数量
      KAFKA_MIN_INSYNC_REPLICAS: 1 # partition的leader节点要求当前在线的replica节点的数量

关于LISTENER相关的几个配置（用于集群访问）更多的可以看下：8.2 对容器外应用提供服务。

参见：

Running Kafka in Production

8.2 对容器外应用提供服务 {#DOCKER_OUT_NET}

在docker中部署集群有一个比较大的问题就是容器内部和外部的网络访问地址是隔离的，而kafka集群部分节点的相互发现是根据配置：KAFKA_ADVERTISED_LISTENERS来进行通知的。

如果该配置内的地址填写的是127.0.0.1这样的回环地址或容器外的IP，那么容器内各kafka节点之间的通讯就会有问题（因为容器内各节点拿到的配置地址都是容器外的IP）。而如果将该配置内的地址都配置成docker容器的名字，那么在容器内部的流量是没问题了，但外部访问kafka服务的应用程序拿到的地址则是容器的名字，就没法访问了。

所以对于需要向容器外部环境的应用提供服务的情况来说，需要做好几项配置的调整（这里说的配置都是kafka的配置，不涉及到zookeeper的配置，事实上集群部署的配置中zookeeper相关的内容非常简单）：

KAFKA_LISTENERS: "INSIDE://0.0.0.0:9093,OUTSIDE://0.0.0.0:9092"
KAFKA_ADVERTISED_LISTENERS: "INSIDE://kafka_1:9093,OUTSIDE://127.0.0.1:19092"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT"
KAFKA_INTER_BROKER_LISTENER_NAME: INSIDE

kafka的配置中，现在可以将内部流量和外部流量的监听地址分离开来，在配置LISTENERS相关的配置时，使用,将INSIDE和OUTSIDE隔离开来即可。一般来说，INSIDE的地址会配置成当前节点的容器名，或者就直接设置成0.0.0.0。而OUTSIDE则根据自身需求设置即可，这里的范例是给本机开发测试用，因此设置的是127.0.0.1。

KAFKA_INTER_BROKER_LISTENER_NAME配置项则是告诉kafka，集群各broker节点之间是使用INSIDE还是OUTSIDE配置作为集群内部流量的通讯地址。此外需要注意的是，该配置的INSIDE和OUTSIDE监听的端口是不可以重复的，因为实际上kafka就是开了两个端口都在监听。

一般第一次在本地设置集群进行开发和调试的时候，这里是个大坑，非常麻烦。配置不正确就会发现kafka完全无法通讯。

8.3 docker-compose scale

一般来说，kafka service的配置不适合在配置文件中只设置一份，然后使用docker-compose scale的方法进行横向扩展。

适用scale的场景只有完全无状态，且各个节点之间的配置完全相同的情况，而kafka各节点一般最好设置自身的container_name，然后在监听地址中使用正确的容器名作为地址，来进行相互通讯。

8.4 yaml配置重用

因为无法使用scale的缘故，必须手写大量的kafka service节点yaml配置，这倒也不算是大问题。关键的问题在于有大量重复的配置项，如果后面要修改，就很麻烦，怕漏改或者改错。

因此最好的方法是使用yaml的配置重用，来设置共通的配置，然后像变量一样重用。这可以参见我之前提到的范例配置文件：

x-kafka-environment-defaults: &KAFKA_ENV_DEFAULTS
  ...
  # 在这里放默认的配置
  ...

services:
  kafka_1:
    ...
    environment:
      ...
      <<: *KAFKA_ENV_DEFAULTS # 这样就把作为变量的配置全部导入到这个点上了

8.4 相关参考

9. 写性能与安全性

在进行测试的过程中，发现写入的速度比较慢，基本上每次写入在kafka集群这边会耗时1秒多，完全不能接受了。之前的博文中也提到了，集群安全性和写入性能是反比的，主要有几项因素：

producer的写入模式：同步、异步
- 异步拥有最佳的性能，但安全性极差
- 同步性能很差，但安全性有保证
acks写入的集群同步模式：-1完全同步、0完全不等待同步、1Leader节点同步
- 0拥有最佳性能，最低的安全性
- -1拥有最佳性能，但性能最低
- 1则比较均衡
partition数量：acks如果为-1，则需要同步所有节点，partition数量越多则性能越低

后续进行了一些研究和测试。

集群共3个broker，topic分片如下：

Topic:work-topic	PartitionCount:3	ReplicationFactor:3	Configs:
	Topic: work-topic	Partition: 0	Leader: 2	Replicas: 2,0,1	Isr: 2,0,1
	Topic: work-topic	Partition: 1	Leader: 1	Replicas: 1,2,0	Isr: 1,2,0
	Topic: work-topic	Partition: 2	Leader: 0	Replicas: 0,1,2	Isr: 0,1,2

查了下官方配置，producer.acks这个现在放在3.3 Producer Configs里，命名为acks（链接）。需要注意的是，这一项配置并不是服务端的配置项，而是连接上来的客户端producer所进行的设置，是否acks根据客户端producer的要求而变动。这很反直觉，我一开始一直都以为这是服务端的配置项，没想到居然是客户端的。

acks在kafka-go的使用，可以查看注释：kafka-go/writer.go，默认是-1，也就是最安全但最慢的那种。

此外，写入模式是同步还是异步也是客户端设置，见：kafka-go/writer.go。

在上面提到的几项要素中，集群规模和partition数量之类都是业务要求，一般不会轻易变动，所以测试主要是实验在不同写入模式和acks情况下的性能变动。

测试：

同步 -1 1秒+
同步 1  1秒+
同步 0  1秒+
异步 -1 0.2ms 几乎瞬间完成
异步 1  0.2ms 几乎瞬间完成
异步 0  0.2ms 几乎瞬间完成

结论：性能只在于是否将客户端设置成异步写入，acks对性能的影响微乎其微。

但上述的测试是在MAC本地环境进行的，有几项因素不够稳定：

kafka集群的内存很小
磁盘IO和实际情况差别较大
集群规模过小
partition数量很少（集群和partition数量很小能够部分解释为什么acks的改动基本上不影响性能）

因此上述测试的结论主要是参考价值，不能作为最终结论。如果后续需要严谨结论的话，需要在真实机器上测试，并需要开启go的profiling，观察下kafka类库中的写入到底是怎么完成的，以及kafka集群的响应情况。此外，即便是模拟集群1秒左右的同步写入速度也实在是太慢了，后续还需要深入profiling，到底这1秒做了什么（无论是kafka还是go客户端）。

10. TODO

深入研究Kafka的监控Metrics
Kafka集群同步写入性能较低的原因解析

资料

链接

消息队列设计精要 - 美团点评技术团队

Fri, 26 Apr 2019 02:01:22 GMT

前言
正文
1. 何时需要消息队列
2. 如何设计一个消息队列
3. 总结
- 作者简介

前言

本文源自美团点评技术团队博客，但似乎是因为博客改版的原因，之前本文的链接失效了。我因为有剪藏文章的习惯，因此有幸没有丢失原文内容。而最近在写的消息队列文章中，我希望引用部分内容，而网上已经不好找原文了，因此无奈之下在这里做一份备份转载。

正文

消息队列已经逐渐成为企业IT系统内部通信的核心手段。它具有低耦合、可靠投递、广播、流量控制、最终一致性等一系列功能，成为异步RPC的主要手段之一。

当今市面上有很多主流的消息中间件，如老牌的ActiveMQ、RabbitMQ，炙手可热的Kafka，阿里巴巴自主开发的Notify、MetaQ、RocketMQ等。

本文不会一一介绍这些消息队列的所有特性，而是探讨一下自主开发设计一个消息队列时，你需要思考和设计的重要方面。过程中我们会参考这些成熟消息队列的很多重要思想。

本文首先会阐述什么时候你需要一个消息队列，然后以Push模型为主，从零开始分析设计一个消息队列时需要考虑到的问题，如RPC、高可用、顺序和重复消息、可靠投递、消费关系解析等。

也会分析以Kafka为代表的pull模型所具备的优点。最后是一些高级主题，如用批量/异步提高性能、pull模型的系统设计理念、存储子系统的设计、流量控制的设计、公平调度的实现等。其中最后四个方面会放在下篇讲解。

1. 何时需要消息队列

当你需要使用消息队列时，首先需要考虑它的必要性。可以使用mq的场景有很多，最常用的几种，是做业务解耦/最终一致性/广播/错峰流控等。反之，如果需要强一致性，关注业务逻辑的处理结果，则RPC显得更为合适。

1.1 解耦

解耦是消息队列要解决的最本质问题。所谓解耦，简单点讲就是一个事务，只关心核心的流程。而需要依赖其他系统但不那么重要的事情，有通知即可，无需等待结果。换句话说，基于消息的模型，关心的是“通知”，而非“处理”。

比如在美团旅游，我们有一个产品中心，产品中心上游对接的是主站、移动后台、旅游供应链等各个数据源；下游对接的是筛选系统、API系统等展示系统。当上游的数据发生变更的时候，如果不使用消息系统，势必要调用我们的接口来更新数据，就特别依赖产品中心接口的稳定性和处理能力。但其实，作为旅游的产品中心，也许只有对于旅游自建供应链，产品中心更新成功才是他们关心的事情。而对于团购等外部系统，产品中心更新成功也好、失败也罢，并不是他们的职责所在。他们只需要保证在信息变更的时候通知到我们就好了。

而我们的下游，可能有更新索引、刷新缓存等一系列需求。对于产品中心来说，这也不是我们的职责所在。说白了，如果他们定时来拉取数据，也能保证数据的更新，只是实时性没有那么强。但使用接口方式去更新他们的数据，显然对于产品中心来说太过于“重量级”了，只需要发布一个产品ID变更的通知，由下游系统来处理，可能更为合理。

再举一个例子，对于我们的订单系统，订单最终支付成功之后可能需要给用户发送短信积分什么的，但其实这已经不是我们系统的核心流程了。如果外部系统速度偏慢（比如短信网关速度不好），那么主流程的时间会加长很多，用户肯定不希望点击支付过好几分钟才看到结果。那么我们只需要通知短信系统“我们支付成功了”，不一定非要等待它处理完成。

1.2 最终一致性

最终一致性指的是两个系统的状态保持一致，要么都成功，要么都失败。当然有个时间限制，理论上越快越好，但实际上在各种异常的情况下，可能会有一定延迟达到最终一致状态，但最后两个系统的状态是一样的。

业界有一些为“最终一致性”而生的消息队列，如Notify（阿里）、QMQ（去哪儿）等，其设计初衷，就是为了交易系统中的高可靠通知。

以一个银行的转账过程来理解最终一致性，转账的需求很简单，如果A系统扣钱成功，则B系统加钱一定成功。反之则一起回滚，像什么都没发生一样。

然而，这个过程中存在很多可能的意外：

A扣钱成功，调用B加钱接口失败。
A扣钱成功，调用B加钱接口虽然成功，但获取最终结果时网络异常引起超时。
A扣钱成功，B加钱失败，A想回滚扣的钱，但A机器down机。

可见，想把这件看似简单的事真正做成，真的不那么容易。所有跨VM的一致性问题，从技术的角度讲通用的解决方案是：

强一致性，分布式事务，但落地太难且成本太高，后文会具体提到。
最终一致性，主要是用“记录”和“补偿”的方式。在做所有的不确定的事情之前，先把事情记录下来，然后去做不确定的事情，结果可能是：成功、失败或是不确定，“不确定”（例如超时等）可以等价为失败。成功就可以把记录的东西清理掉了，对于失败和不确定，可以依靠定时任务等方式把所有失败的事情重新搞一遍，直到成功为止。

回到刚才的例子，系统在A扣钱成功的情况下，把要给B“通知”这件事记录在库里（为了保证最高的可靠性可以把通知B系统加钱和扣钱成功这两件事维护在一个本地事务里），通知成功则删除这条记录，通知失败或不确定则依靠定时任务补偿性地通知我们，直到我们把状态更新成正确的为止。

整个这个模型依然可以基于RPC来做，但可以抽象成一个统一的模型，基于消息队列来做一个“企业总线”。

具体来说，本地事务维护业务变化和通知消息，一起落地（失败则一起回滚），然后RPC到达broker，在broker成功落地后，RPC返回成功，本地消息可以删除。否则本地消息一直靠定时任务轮询不断重发，这样就保证了消息可靠落地broker。

Broker往consumer发送消息的过程类似，一直发送消息，直到consumer发送消费成功确认。

我们先不理会重复消息的问题，通过两次消息落地加补偿，下游是一定可以收到消息的。然后依赖状态机版本号等方式做判重，更新自己的业务，就实现了最终一致性。

最终一致性不是消息队列的必备特性，但确实可以依靠消息队列来做最终一致性的事情。另外，所有不保证100%不丢消息的消息队列，理论上无法实现最终一致性。好吧，应该说理论上的100%，排除系统严重故障和bug。

像Kafka一类的设计，在设计层面上就有丢消息的可能（比如定时刷盘，如果掉电就会丢消息）。哪怕只丢千分之一的消息，业务也必须用其他的手段来保证结果正确。

1.3 广播

消息队列的基本功能之一是进行广播。如果没有消息队列，每当一个新的业务方接入，我们都要联调一次新接口。有了消息队列，我们只需要关心消息是否送达了队列，至于谁希望订阅，是下游的事情，无疑极大地减少了开发和联调的工作量。

比如本文开始提到的产品中心发布产品变更的消息，以及景点库很多去重更新的消息，可能“关心”方有很多个，但产品中心和景点库只需要发布变更消息即可，谁关心谁接入。

1.4 错峰与流控

试想上下游对于事情的处理能力是不同的。比如，Web前端每秒承受上千万的请求，并不是什么神奇的事情，只需要加多一点机器，再搭建一些LVS负载均衡设备和Nginx等即可。但数据库的处理能力却十分有限，即使使用SSD加分库分表，单机的处理能力仍然在万级。由于成本的考虑，我们不能奢求数据库的机器数量追上前端。

这种问题同样存在于系统和系统之间，如短信系统可能由于短板效应，速度卡在网关上（每秒几百次请求），跟前端的并发量不是一个数量级。但用户晚上个半分钟左右收到短信，一般是不会有太大问题的。如果没有消息队列，两个系统之间通过协商、滑动窗口等复杂的方案也不是说不能实现。但系统复杂性指数级增长，势必在上游或者下游做存储，并且要处理定时、拥塞等一系列问题。而且每当有处理能力有差距的时候，都需要单独开发一套逻辑来维护这套逻辑。所以，利用中间系统转储两个系统的通信内容，并在下游系统有能力处理这些消息的时候，再处理这些消息，是一套相对较通用的方式。

总而言之，消息队列不是万能的。对于需要强事务保证而且延迟敏感的，RPC是优于消息队列的。

对于一些无关痛痒，或者对于别人非常重要但是对于自己不是那么关心的事情，可以利用消息队列去做。

支持最终一致性的消息队列，能够用来处理延迟不那么敏感的“分布式事务”场景，而且相对于笨重的分布式事务，可能是更优的处理方式。

当上下游系统处理能力存在差距的时候，利用消息队列做一个通用的“漏斗”。在下游有能力处理的时候，再进行分发。如果下游有很多系统关心你的系统发出的通知的时候，果断地使用消息队列吧。

2. 如何设计一个消息队列

2.1 综述

我们现在明确了消息队列的使用场景，下一步就是如何设计实现一个消息队列了。

基于消息的系统模型，不一定需要broker(消息队列服务端)。市面上的的Akka（actor模型）、ZeroMQ等，其实都是基于消息的系统设计范式，但是没有broker。

我们之所以要设计一个消息队列，并且配备broker，无外乎要做两件事情：

消息的转储，在更合适的时间点投递，或者通过一系列手段辅助消息最终能送达消费机。
规范一种范式和通用的模式，以满足解耦、最终一致性、错峰等需求。

掰开了揉碎了看，最简单的消息队列可以做成一个消息转发器，把一次RPC做成两次RPC。发送者把消息投递到服务端（以下简称broker），服务端再将消息转发一手到接收端，就是这么简单。

一般来讲，设计消息队列的整体思路是先build一个整体的数据流,例如producer发送给broker,broker发送给consumer,consumer回复消费确认，broker删除/备份消息等。

利用RPC将数据流串起来。然后考虑RPC的高可用性，尽量做到无状态，方便水平扩展。

之后考虑如何承载消息堆积，然后在合适的时机投递消息，而处理堆积的最佳方式，就是存储，存储的选型需要综合考虑性能/可靠性和开发维护成本等诸多因素。

为了实现广播功能，我们必须要维护消费关系，可以利用zk/config server等保存消费关系。

在完成了上述几个功能后，消息队列基本就实现了。然后我们可以考虑一些高级特性，如可靠投递，事务特性，性能优化等。

下面我们会以设计消息队列时重点考虑的模块为主线，穿插灌输一些消息队列的特性实现方法，来具体分析设计实现一个消息队列时的方方面面。

2.2 实现队列基本功能

2.2.1 RPC通信协议

刚才讲到，所谓消息队列，无外乎两次RPC加一次转储，当然需要消费端最终做消费确认的情况是三次RPC。既然是RPC，就必然牵扯出一系列话题，什么负载均衡啊、服务发现啊、通信协议啊、序列化协议啊，等等。在这一块，我的强烈建议是不要重复造轮子。利用公司现有的RPC框架：Thrift也好，Dubbo也好，或者是其他自定义的框架也好。因为消息队列的RPC，和普通的RPC没有本质区别。当然了，自主利用Memchached或者Redis协议重新写一套RPC框架并非不可（如MetaQ使用了自己封装的Gecko NIO框架，卡夫卡也用了类似的协议）。但实现成本和难度无疑倍增。排除对效率的极端要求，都可以使用现成的RPC框架。

简单来讲，服务端提供两个RPC服务，一个用来接收消息，一个用来确认消息收到。并且做到不管哪个server收到消息和确认消息，结果一致即可。当然这中间可能还涉及跨IDC的服务的问题。这里和RPC的原则是一致的，尽量优先选择本机房投递。你可能会问，如果producer和consumer本身就在两个机房了，怎么办？首先，broker必须保证感知的到所有consumer的存在。其次，producer尽量选择就近的机房就好了。

2.2.2 高可用

其实所有的高可用，是依赖于RPC和存储的高可用来做的。先来看RPC的高可用，美团的基于MTThrift的RPC框架，阿里的Dubbo等，其本身就具有服务自动发现，负载均衡等功能。而消息队列的高可用，只要保证broker接受消息和确认消息的接口是幂等的，并且consumer的几台机器处理消息是幂等的，这样就把消息队列的可用性，转交给RPC框架来处理了。

那么怎么保证幂等呢？最简单的方式莫过于共享存储。broker多机器共享一个DB或者一个分布式文件/kv系统，则处理消息自然是幂等的。就算有单点故障，其他节点可以立刻顶上。另外failover可以依赖定时任务的补偿，这是消息队列本身天然就可以支持的功能。存储系统本身的可用性我们不需要操太多心，放心大胆的交给DBA们吧！

对于不共享存储的队列，如Kafka使用分区加主备模式，就略微麻烦一些。需要保证每一个分区内的高可用性，也就是每一个分区至少要有一个主备且需要做数据的同步，关于这块HA的细节，可以参考下篇pull模型消息系统设计。

2.2.3 服务端承载消息堆积的能力

消息到达服务端如果不经过任何处理就到接收者了，broker就失去了它的意义。为了满足我们错峰/流控/最终可达等一系列需求，把消息存储下来，然后选择时机投递就显得是顺理成章的了。

只是这个存储可以做成很多方式。比如存储在内存里，存储在分布式KV里，存储在磁盘里，存储在数据库里等等。但归结起来，主要有持久化和非持久化两种。

持久化的形式能更大程度地保证消息的可靠性（如断电等不可抗外力），并且理论上能承载更大限度的消息堆积（外存的空间远大于内存）。

但并不是每种消息都需要持久化存储。很多消息对于投递性能的要求大于可靠性的要求，且数量极大（如日志）。这时候，消息不落地直接暂存内存，尝试几次failover，最终投递出去也未尝不可。

市面上的消息队列普遍两种形式都支持。当然具体的场景还要具体结合公司的业务来看。

2.2.4 存储子系统的选择

我们来看看如果需要数据落地的情况下各种存储子系统的选择。理论上，从速度来看，文件系统>分布式KV（持久化）>分布式文件系统>数据库，而可靠性却截然相反。还是要从支持的业务场景出发作出最合理的选择，如果你们的消息队列是用来支持支付/交易等对可靠性要求非常高，但对性能和量的要求没有这么高，而且没有时间精力专门做文件存储系统的研究，DB是最好的选择。

但是DB受制于IOPS，如果要求单broker 5位数以上的QPS性能，基于文件的存储是比较好的解决方案。整体上可以采用数据文件+索引文件的方式处理，具体这块的设计比较复杂，可以参考下篇的存储子系统设计。

分布式KV（如MongoDB，HBase）等，或者持久化的Redis，由于其编程接口较友好，性能也比较可观，如果在可靠性要求不是那么高的场景，也不失为一个不错的选择。

2.2.5 消费关系解析

现在我们的消息队列初步具备了转储消息的能力。下面一个重要的事情就是解析发送接收关系，进行正确的消息投递了。

市面上的消息队列定义了一堆让人晕头转向的名词，如JMS 规范中的Topic/Queue，Kafka里面的Topic/Partition/ConsumerGroup，RabbitMQ里面的Exchange等等。抛开现象看本质，无外乎是单播与广播的区别。所谓单播，就是点到点；而广播，是一点对多点。当然，对于互联网的大部分应用来说，组间广播、组内单播是最常见的情形。

消息需要通知到多个业务集群，而一个业务集群内有很多台机器，只要一台机器消费这个消息就可以了。

当然这不是绝对的，很多时候组内的广播也是有适用场景的，如本地缓存的更新等等。另外，消费关系除了组内组间，可能会有多级树状关系。这种情况太过于复杂，一般不列入考虑范围。所以，一般比较通用的设计是支持组间广播，不同的组注册不同的订阅。组内的不同机器，如果注册一个相同的ID，则单播；如果注册不同的ID(如IP地址+端口)，则广播。

至于广播关系的维护，一般由于消息队列本身都是集群，所以都维护在公共存储上，如config server、zookeeper等。维护广播关系所要做的事情基本是一致的:

发送关系的维护。
发送关系变更时的通知。

2.3 队列高级特性设计

上面都是些消息队列基本功能的实现，下面来看一些关于消息队列特性相关的内容，不管可靠投递/消息丢失与重复以及事务乃至于性能，不是每个消息队列都会照顾到，所以要依照业务的需求，来仔细衡量各种特性实现的成本，利弊，最终做出最为合理的设计。

2.3.1 可靠投递（最终一致性）

这是个激动人心的话题，完全不丢消息，究竟可不可能？答案是，完全可能，前提是消息可能会重复，并且，在异常情况下，要接受消息的延迟。

方案说简单也简单，就是每当要发生不可靠的事情（RPC等）之前，先将消息落地，然后发送。当失败或者不知道成功失败（比如超时）时，消息状态是待发送，定时任务不停轮询所有待发送消息，最终一定可以送达。

具体来说：

producer往broker发送消息之前，需要做一次落地。
请求到server后，server确保数据落地后再告诉客户端发送成功。
支持广播的消息队列需要对每个待发送的endpoint，持久化一个发送状态，直到所有endpoint状态都OK才可删除消息。

对于各种不确定（超时、down机、消息没有送达、送达后数据没落地、数据落地了回复没收到），其实对于发送方来说，都是一件事情，就是消息没有送达。

重推消息所面临的问题就是消息重复。重复和丢失就像两个噩梦，你必须要面对一个。好在消息重复还有处理的机会，消息丢失再想找回就难了。

Anyway，作为一个成熟的消息队列，应该尽量在各个环节减少重复投递的可能性，不能因为重复有解决方案就放纵的乱投递。

最后说一句，不是所有的系统都要求最终一致性或者可靠投递，比如一个论坛系统、一个招聘系统。一个重复的简历或话题被发布，可能比丢失了一个发布显得更让用户无法接受。不断重复一句话，任何基础组件要服务于业务场景。

2.3.1.1 消费确认

当broker把消息投递给消费者后，消费者可以立即响应我收到了这个消息。但收到了这个消息只是第一步，我能不能处理这个消息却不一定。或许因为消费能力的问题，系统的负荷已经不能处理这个消息；或者是刚才状态机里面提到的消息不是我想要接收的消息，主动要求重发。

把消息的送达和消息的处理分开，这样才真正的实现了消息队列的本质-解耦。所以，允许消费者主动进行消费确认是必要的。当然，对于没有特殊逻辑的消息，默认Auto Ack也是可以的，但一定要允许消费方主动ack。

对于正确消费ack的，没什么特殊的。但是对于reject和error，需要特别说明。reject这件事情，往往业务方是无法感知到的，系统的流量和健康状况的评估，以及处理能力的评估是一件非常复杂的事情。举个极端的例子，收到一个消息开始build索引，可能这个消息要处理半个小时，但消息量却是非常的小。所以reject这块建议做成滑动窗口/线程池类似的模型来控制，消费能力不匹配的时候，直接拒绝，过一段时间重发，减少业务的负担。

但业务出错这件事情是只有业务方自己知道的，就像上文提到的状态机等等。这时应该允许业务方主动ack error，并可以与broker约定下次投递的时间。

2.3.1.2 重复消息和顺序消息

上文谈到重复消息是不可能100%避免的，除非可以允许丢失，那么，顺序消息能否100%满足呢? 答案是可以，但条件更为苛刻：

允许消息丢失。
从发送方到服务方到接受者都是单点单线程。

所以绝对的顺序消息基本上是不能实现的，当然在METAQ/Kafka等pull模型的消息队列中，单线程生产/消费，排除消息丢失，也是一种顺序消息的解决方案。

一般来讲，一个主流消息队列的设计范式里，应该是不丢消息的前提下，尽量减少重复消息，不保证消息的投递顺序。

谈到重复消息，主要是两个话题：

如何鉴别消息重复，并幂等的处理重复消息。
一个消息队列如何尽量减少重复消息的投递。

先来看看第一个话题，每一个消息应该有它的唯一身份。不管是业务方自定义的，还是根据IP/PID/时间戳生成的MessageId，如果有地方记录这个MessageId，消息到来是能够进行比对就能完成重复的鉴定。数据库的唯一键/bloom filter/分布式KV中的key，都是不错的选择。由于消息不能被永久存储，所以理论上都存在消息从持久化存储移除的瞬间上游还在投递的可能（上游因种种原因投递失败，不停重试，都到了下游清理消息的时间）。这种事情都是异常情况下才会发生的，毕竟是小众情况。两分钟消息都还没送达，多送一次又能怎样呢？幂等的处理消息是一门艺术，因为种种原因重复消息或者错乱的消息还是来到了，说两种通用的解决方案：

版本号。
状态机。

版本号

举个简单的例子，一个产品的状态有上线/下线状态。如果消息1是下线，消息2是上线。不巧消息1判重失败，被投递了两次，且第二次发生在2之后，如果不做重复性判断，显然最终状态是错误的。

但是，如果每个消息自带一个版本号。上游发送的时候，标记消息1版本号是1，消息2版本号是2。如果再发送下线消息，则版本号标记为3。下游对于每次消息的处理，同时维护一个版本号。

每次只接受比当前版本号大的消息。初始版本为0，当消息1到达时，将版本号更新为1。消息2到来时，因为版本号>1.可以接收，同时更新版本号为2.当另一条下线消息到来时，如果版本号是3.则是真实的下线消息。如果是1，则是重复投递的消息。

如果业务方只关心消息重复不重复，那么问题就已经解决了。但很多时候另一个头疼的问题来了，就是消息顺序如果和想象的顺序不一致。比如应该的顺序是12，到来的顺序是21。则最后会发生状态错误。

参考TCP/IP协议，如果想让乱序的消息最后能够正确的被组织，那么就应该只接收比当前版本号大一的消息。并且在一个session周期内要一直保存各个消息的版本号。

如果到来的顺序是21，则先把2存起来，待2到来后，再处理1，这样重复性和顺序性要求就都达到了。

状态机

基于版本号来处理重复和顺序消息听起来是个不错的主意，但凡事总有瑕疵。使用版本号的最大问题是：

对发送方必须要求消息带业务版本号。
下游必须存储消息的版本号，对于要严格保证顺序的。

还不能只存储最新的版本号的消息，要把乱序到来的消息都存储起来。而且必须要对此做出处理。试想一个永不过期的”session”，比如一个物品的状态，会不停流转于上下线。那么中间环节的所有存储就必须保留，直到在某个版本号之前的版本一个不丢的到来，成本太高。

就刚才的场景看，如果消息没有版本号，该怎么解决呢？业务方只需要自己维护一个状态机，定义各种状态的流转关系。例如，“下线”状态只允许接收”上线”消息，“上线”状态只能接收“下线消息”，如果上线收到上线消息，或者下线收到下线消息，在消息不丢失和上游业务正确的前提下。要么是消息发重了，要么是顺序到达反了。这时消费者只需要把“我不能处理这个消息”告诉投递者，要求投递者过一段时间重发即可。而且重发一定要有次数限制，比如5次，避免死循环，就解决了。

举例子说明，假设产品本身状态是下线，1是上线消息，2是下线消息，3是上线消息，正常情况下，消息应该的到来顺序是123，但实际情况下收到的消息状态变成了3123。

那么下游收到3消息的时候，判断状态机流转是下线->上线，可以接收消息。然后收到消息1，发现是上线->上线，拒绝接收，要求重发。然后收到消息2，状态是上线->下线，于是接收这个消息。

此时无论重发的消息1或者3到来，还是可以接收。另外的重发，在一定次数拒绝后停止重发，业务正确。

2.3.1.3 中间件对于重复消息的处理

回归到消息队列的话题来讲。上述通用的版本号/状态机/ID判重解决方案里，哪些是消息队列该做的、哪些是消息队列不该做业务方处理的呢？其实这里没有一个完全严格的定义，但回到我们的出发点，我们保证不丢失消息的情况下尽量少重复消息，消费顺序不保证。那么重复消息下和乱序消息下业务的正确，应该是由消费方保证的，我们要做的是减少消息发送的重复。

我们无法定义业务方的业务版本号/状态机，如果API里强制需要指定版本号，则显得过于绑架客户了。况且，在消费方维护这么多状态，就涉及到一个消费方的消息落地/多机间的同步消费状态问题，复杂度指数级上升，而且只能解决部分问题。

减少重复消息的关键步骤：

broker记录MessageId，直到投递成功后清除，重复的ID到来不做处理，这样只要发送者在清除周期内能够感知到消息投递成功，就基本不会在server端产生重复消息。
对于server投递到consumer的消息，由于不确定对端是在处理过程中还是消息发送丢失的情况下，有必要记录下投递的IP地址。决定重发之前询问这个IP，消息处理成功了吗？如果询问无果，再重发。

2.3.2 事务

持久性是事务的一个特性，然而只满足持久性却不一定能满足事务的特性。还是拿扣钱/加钱的例子讲。满足事务的一致性特征，则必须要么都不进行，要么都能成功。

解决方案从大方向上有两种：

两阶段提交，分布式事务。
本地事务，本地落地，补偿发送。

分布式事务存在的最大问题是成本太高，两阶段提交协议，对于仲裁down机或者单点故障，几乎是一个无解的黑洞。对于交易密集型或者I/O密集型的应用，没有办法承受这么高的网络延迟，系统复杂性。

并且成熟的分布式事务一定构建与比较靠谱的商用DB和商用中间件上，成本也太高。

那如何使用本地事务解决分布式事务的问题呢？以本地和业务在一个数据库实例中建表为例子，与扣钱的业务操作同一个事务里，将消息插入本地数据库。如果消息入库失败，则业务回滚；如果消息入库成功，事务提交。

然后发送消息（注意这里可以实时发送，不需要等定时任务检出，以提高消息实时性）。以后的问题就是前文的最终一致性问题所提到的了，只要消息没有发送成功，就一直靠定时任务重试。

这里有一个关键的点，本地事务做的，是业务落地和消息落地的事务，而不是业务落地和RPC成功的事务。这里很多人容易混淆，如果是后者，无疑是事务嵌套RPC，是大忌，会有长事务死锁等各种风险。

而消息只要成功落地，很大程度上就没有丢失的风险（磁盘物理损坏除外）。而消息只要投递到服务端确认后本地才做删除，就完成了producer->broker的可靠投递，并且当消息存储异常时，业务也是可以回滚的。

本地事务存在两个最大的使用障碍：

配置较为复杂，“绑架”业务方，必须本地数据库实例提供一个库表。
对于消息延迟高敏感的业务不适用。

话说回来，不是每个业务都需要强事务的。扣钱和加钱需要事务保证，但下单和生成短信却不需要事务，不能因为要求发短信的消息存储投递失败而要求下单业务回滚。所以，一个完整的消息队列应该定义清楚自己可以投递的消息类型，如事务型消息，本地非持久型消息，以及服务端不落地的非可靠消息等。对不同的业务场景做不同的选择。另外事务的使用应该尽量低成本、透明化，可以依托于现有的成熟框架，如Spring的声明式事务做扩展。业务方只需要使用@Transactional标签即可。

2.3.3 性能相关

2.3.3.1 异步/同步

首先澄清一个概念，异步，同步和oneway是三件事。异步，归根结底你还是需要关心结果的，但可能不是当时的时间点关心，可以用轮询或者回调等方式处理结果；同步是需要当时关心的结果的；而oneway是发出去就不管死活的方式，这种对于某些完全对可靠性没有要求的场景还是适用的，但不是我们重点讨论的范畴。

回归来看，任何的RPC都是存在客户端异步与服务端异步的，而且是可以任意组合的：客户端同步对服务端异步，客户端异步对服务端异步，客户端同步对服务端同步，客户端异步对服务端同步。

对于客户端来说，同步与异步主要是拿到一个Result，还是Future(Listenable)的区别。实现方式可以是线程池，NIO或者其他事件机制，这里先不展开讲。

服务端异步可能稍微难理解一点，这个是需要RPC协议支持的。参考servlet 3.0规范，服务端可以吐一个future给客户端，并且在future done的时候通知客户端。

整个过程可以参考下面的代码：

客户端同步服务端异步。

Future<Result> future = request(server); // server立刻返回future
synchronized(future) {
    while(!future.isDone()) {
       future.wait(); // server处理结束后会notify这个future，并修改isdone标志
    }
}
return future.get();

客户端同步服务端同步。

Result result = request(server);

客户端异步服务端同步(这里用线程池的方式)。

Future<Result> future = executor.submit(new Callable() {
    public void call<Result>() {
        result = request(server);
    }
});
return future;

客户端异步服务端异步。

Future<Result> future = request(server); // server立刻返回future

return future;

上面说了这么多，其实是想让大家脱离两个误区：

RPC只有客户端能做异步，服务端不能。
异步只能通过线程池。

那么，服务端使用异步最大的好处是什么呢？说到底，是解放了线程和I/O。试想服务端有一堆I/O等待处理，如果每个请求都需要同步响应，每条消息都需要结果立刻返回，那么就几乎没法做I/O合并（当然接口可以设计成batch的，但可能batch发过来的仍然数量较少）。而如果用异步的方式返回给客户端future，就可以有机会进行I/O的合并，把几个批次发过来的消息一起落地（这种合并对于MySQL等允许batch insert的数据库效果尤其明显），并且彻底释放了线程。不至于说来多少请求开多少线程，能够支持的并发量直线提高。

来看第二个误区，返回future的方式不一定只有线程池。换句话说，可以在线程池里面进行同步操作，也可以进行异步操作，也可以不使用线程池使用异步操作（NIO、事件）。

回到消息队列的议题上，我们当然不希望消息的发送阻塞主流程（前面提到了，server端如果使用异步模型，则可能因消息合并带来一定程度上的消息延迟），所以可以先使用线程池提交一个发送请求，主流程继续往下走。

但是线程池中的请求关心结果吗？Of course，必须等待服务端消息成功落地，才算是消息发送成功。所以这里的模型，准确地说事客户端半同步半异步（使用线程池不阻塞主流程，但线程池中的任务需要等待server端的返回），server端是纯异步。客户端的线程池wait在server端吐回的future上，直到server端处理完毕，才解除阻塞继续进行。

总结一句，同步能够保证结果，异步能够保证效率，要合理的结合才能做到最好的效率。

2.3.3.2 批量

谈到批量就不得不提生产者消费者模型。但生产者消费者模型中最大的痛点是：消费者到底应该何时进行消费。大处着眼来看，消费动作都是事件驱动的。主要事件包括：

攒够了一定数量。
到达了一定时间。
队列里有新的数据到来。

对于及时性要求高的数据，可用采用方式3来完成，比如客户端向服务端投递数据。只要队列有数据，就把队列中的所有数据刷出，否则将自己挂起，等待新数据的到来。

在第一次把队列数据往外刷的过程中，又积攒了一部分数据，第二次又可以形成一个批量。伪代码如下:

Executor executor = Executors.newFixedThreadPool(4);
final BlockingQueue<Message> queue = new ArrayBlockingQueue<>();

private Runnable task = new Runnable({ // 这里由于共享队列，Runnable可以复用，故做成全局的
   public void run() {
      List<Message> messages  = new ArrayList<>(20);
      queue.drainTo(messages，20);
      doSend(messages); // 阻塞，在这个过程中会有新的消息到来，如果4个线程都占满，队列就有机会囤新的消息
   }
});

public void send(Message message) {
    queue.offer(message);
    executor.submit(task);
}

这种方式是消息延迟和批量的一个比较好的平衡，但优先响应低延迟。延迟的最高程度由上一次发送的等待时间决定。但可能造成的问题是发送过快的话批量的大小不够满足性能的极致。

Executor executor = Executors.newFixedThreadPool(4);
final BlockingQueue<Message> queue = new ArrayBlockingQueue<>();
volatile long last = System.currentMills();

Executors.newSingleThreadScheduledExecutor().submit(new Runnable() {
   flush();
}，500，500，TimeUnits.MILLS);

private Runnable task = new Runnable({ // 这里由于共享队列，Runnable可以复用，顾做成全局的。
   public void run() {
      List<Message> messages  = new ArrayList<>(20);
      queue.drainTo(messages，20);
      doSend(messages); // 阻塞，在这个过程中会有新的消息到来，如果4个线程都占满，队列就有机会屯新的消息。
   }
});

public void send(Message message) {
    last = System.currentMills();
    queue.offer(message);
    flush();
}

private void flush() {
 if (queue.size > 200 || System.currentMills() - last > 200) {
       executor.submit(task)
  }
}

相反对于可以用适量的延迟来换取高性能的场景来说，用定时/定量二选一的方式可能会更为理想，既到达一定数量才发送，但如果数量一直达不到，也不能干等，有一个时间上限。

具体说来，在上文的submit之前，多判断一个时间和数量，并且Runnable内部维护一个定时器，避免没有新任务到来时旧的任务永远没有机会触发发送条件。对于server端的数据落地，使用这种方式就非常方便。

最后啰嗦几句，曾经有人问我，为什么网络请求小包合并成大包会提高性能？主要原因有两个：

减少无谓的请求头，如果你每个请求只有几字节，而头却有几十字节，无疑效率非常低下。
减少回复的ack包个数。把请求合并后，ack包数量必然减少，确认和重发的成本就会降低。

2.4 push还是pull

上文提到的消息队列，大多是针对push模型的设计。现在市面上有很多经典的也比较成熟的pull模型的消息队列，如Kafka、MetaQ等。这跟JMS中传统的push方式有很大的区别，可谓另辟蹊径。

我们简要分析下push和pull模型各自存在的利弊。

2.4.1 慢消费

慢消费无疑是push模型最大的致命伤，穿成流水线来看，如果消费者的速度比发送者的速度慢很多，势必造成消息在broker的堆积。假设这些消息都是有用的无法丢弃的，消息就要一直在broker端保存。当然这还不是最致命的，最致命的是broker给consumer推送一堆consumer无法处理的消息，consumer不是reject就是error，然后来回踢皮球。

反观pull模式，consumer可以按需消费，不用担心自己处理不了的消息来骚扰自己，而broker堆积消息也会相对简单，无需记录每一个要发送消息的状态，只需要维护所有消息的队列和偏移量就可以了。所以对于建立索引等慢消费，消息量有限且到来的速度不均匀的情况，pull模式比较合适。

2.4.2 消息延迟与忙等

这是pull模式最大的短板。由于主动权在消费方，消费方无法准确地决定何时去拉取最新的消息。如果一次pull取到消息了还可以继续去pull，如果没有pull取到则需要等待一段时间重新pull。

但等待多久就很难判定了。你可能会说，我可以有xx动态pull取时间调整算法，但问题的本质在于，有没有消息到来这件事情决定权不在消费方。也许1分钟内连续来了1000条消息，然后半个小时没有新消息产生，可能你的算法算出下次最有可能到来的时间点是31分钟之后，或者60分钟之后，结果下条消息10分钟后到了，是不是很让人沮丧？当然也不是说延迟就没有解决方案了，业界较成熟的做法是从短时间开始（不会对broker有太大负担），然后指数级增长等待。比如开始等5ms，然后10ms，然后20ms，然后40ms……直到有消息到来，然后再回到5ms。

即使这样，依然存在延迟问题：假设40ms到80ms之间的50ms消息到来，消息就延迟了30ms，而且对于半个小时来一次的消息，这些开销就是白白浪费的。

在阿里的RocketMq里，有一种优化的做法-长轮询，来平衡推拉模型各自的缺点。基本思路是:消费者如果尝试拉取失败，不是直接return,而是把连接挂在那里wait,服务端如果有新的消息到来，把连接notify起来，这也是不错的思路。但海量的长连接block对系统的开销还是不容小觑的，还是要合理的评估时间间隔，给wait加一个时间上限比较好~

2.4.3 顺序消息

如果push模式的消息队列，支持分区，单分区只支持一个消费者消费，并且消费者只有确认一个消息消费后才能push送另外一个消息，还要发送者保证全局顺序唯一，听起来也能做顺序消息，但成本太高了，尤其是必须每个消息消费确认后才能发下一条消息，这对于本身堆积能力和慢消费就是瓶颈的push模式的消息队列，简直是一场灾难。

反观pull模式，如果想做到全局顺序消息，就相对容易很多：

producer对应partition，并且单线程。
consumer对应partition，消费确认（或批量确认），继续消费即可。

所以对于日志push送这种最好全局有序，但允许出现小误差的场景，pull模式非常合适。如果你不想看到通篇乱套的日志~~Anyway，需要顺序消息的场景还是比较有限的而且成本太高，请慎重考虑。

3. 总结

本文从为何使用消息队列开始讲起，然后主要介绍了如何从零开始设计一个消息队列，包括RPC、事务、最终一致性、广播、消息确认等关键问题。并对消息队列的push、pull模型做了简要分析，最后从批量和异步角度，分析了消息队列性能优化的思路。下篇会着重介绍一些高级话题，如存储系统的设计、流控和错峰的设计、公平调度等。希望通过这些，让大家对消息队列有个提纲挈领的整体认识，并给自主开发消息队列提供思路。另外，本文主要是源自自己在开发消息队列中的思考和读源码时的体会，比较不”官方”，也难免会存在一些漏洞，欢迎大家多多交流。

后续我们还会推出消息队列设计高级篇，内容会涵盖以下方面：

pull模型消息系统设计理念
存储子系统设计
流量控制
公平调度

敬请期待哦~

作者简介

王烨，现在是美团旅游后台研发组的程序猿，之前曾经在百度、去哪和优酷工作过，专注Java后台开发。对于网络编程和并发编程具有浓厚的兴趣，曾经做过一些基础组件，也翻过一些源码，属于比较典型的宅男技术控。期待能够与更多知己，在coding的路上并肩前行~

Blog by Jonathan Dai

轻量级健身综合入门指引

1. 前言

2. 目标

2.1 目标分类/衡量

2.2 目标设定

3. 知识与原理

3.1 RM - repetition maximum

3.2 RM与训练效果

3.3 单部位训练的多种动作

3.4 重复次数与组数的意义

3.5 DOMS - 延迟性肌肉酸痛

3.6 休息拉伸

3.7 训练周期

3.8 神经的募集

3.9 肌肉生长的理论

3.10 识别肌肉

3.11 中立位、关节锁死

3.12 向心收缩、离心收缩、等长收缩

3.13 动作行程

3.14 动作稳定性

3.15 多关节与单关节

3.16 深层肌肉与姿势稳定性

3.17 坚持

3.18 有氧训练的选择

3.19 常见误区

5. 如何开始

准备工作

确认合适自己的训练重量

制定训练计划

如何进步

6. 如何居家训练

6.1 明确目标

6.2 设备需求

6.3 实际安装组合效果及动作选择

6.3.1 胸部肌群

6.3.2 背部肌群

6.3.3 肱二头肌

6.3.4 肱三头肌

6.3.5 肩部

6.3.6 腹部 + 下背

6.3.7 臀腿

神奇的Node.js map中+=async问题

1. 看代码

2. 原理

Git Revert Trap

1. See an example

Charles证书刷新

1. 前言

2. 几个方法

2.1 重置根证书

2.2 删除并重新生成证书

ngrok tutorial

1. 前言

2. 安装准备

3. 使用范例

3.1 准备本地http服务

3.2 启动ngrok

3.3 测试

Swift iOS App唤起支付宝支付的简单教程

1. 前言

2. 创建iOS项目

3. 安装cocospods

4. 安装Alipay SDK

5. 桥接Alipay SDK的Header文件

6. 实现唤起Alipay

Obsidian插件经验

1. 前言

2. 基础

3. 代码

4. 问题

Reference

Evernote: The Knowledge Database

1. 前言

2. 知识管理

3. Evernote使用

3.1 网页剪藏

3.2 微信剪藏

3.3 Tag管理

3.4 搜索

NAS备份计划及 PC备份软件推荐