介绍

受到Hexo这样的基于nodejs的，可以本地编辑的博客的启发，typexo旨在对于typecho的博客开发类似的功能。本项目typexo-cli是本地端的实现，用于编辑内容、本地测试、远程部署。

目前本项目仅针对MySQL数据库进行开发，其他数据库日后会进行支持。

目前本项目不支持typecho的attachments, 解决方案是使用自己的图床, 该功能可能会在日后支持（可能性不大）。

请注意：服务端程序会直接对数据库进行操作，如果你不知道程序在干什么，请勿执行。硬盘有价，数据无价。请确保在操作之前对数据库进行备份。

• 介绍
• 环境及依赖项
• 术语
• 原理以及流程
• 准备就绪，开始！
  • 在服务器搭好typexo-server
  • 配置config.yml
  • Quick Start
• 关于本地测试服务器
• 命令说明
  • ✅ init
  • ✅ rm
  • ✅ commit
  • ✅ discard-change
  • ✅ status
  • ✅ merge {prod|test}
  • ✅ fix-git-utf8
  • ✅ prod-test
  • ✅ clone
  • ✅ pull {prod|test}
  • ✅ push
  • ✅ format
  • ✅ new [--draft] {post|page} TITLE
  • ✅ import [--draft] {post|page} FILE
  • 🚧 diff {prod|test}
  • ✅ deploy {prod|test}
  • 🚧 server
• 配置文件
  • prod字段
  • test字段
  • fields字段
  • defaultFields字段
  • defaultSlugType字段
  • repo字段
• 使用注意事项
  • 不得编辑的文件
  • 可能出现的合并冲突
    • meta顺序更换问题
    • 以cid作为slug的问题

环境及依赖项

• Client
  • Python 3.6+
  • Linux (WSL)
  • Git
  • MySQL (可选，用于本地测试服务器)
  • PHP (可选，用于本地测试服务器)
  • Python依赖项
    • pyyaml
    • click
    • requests
    • GitPython
• Server
  • Python 3.6+
  • MySQL (目前仅支持此数据库)
  • Python依赖项
    • pyyaml
    • pymysql
    • pandas
    • uvicorn
    • requests
    • fastapi
    • typing
    • pydantic

术语

• prod - 生产环境
• test - 测试环境，即本地测试服务器
• workplace ( wp ) - 工作区

原理以及流程

主要原理如上图。同一种颜色代表同一个流程；实线代表命令，虚线代表内部流程。

本地使用git进行管理分支，总共有三个分支:

• master: 主分支，用于编辑；
• prod: 生产环境拉去下来的分支，用于merge conflict。注意：这个分支不得有任何改动，只能执行typexo的pull prod命令，自动完成。若出现错误，请执行discard-change命令；
• test: 本地测试分支 (可选)。本地经过测试后，若想同步测试服务器上的结果，可以通过pull test命令merge到主分支，随后测试分支将被删除，是一个临时分支。

注意：

• 在本项目中，所有的checkout (切换分支) 操作的先决条件是 working tree clean ，如果还有更改没有提交，将会拒绝分支切换请求；
• test分支在进行任意的合并操作之后会被自动删除，prod分支不会。如果没有合理的原因，请不要删除prod分支，否则会引发数据混乱；
• 在进行deploy的时候，我们并没有采用git的两个分支之间的diff，而是直接再度拉取服务器端的数据，直接进行比对。这样做的原因其实只是GitPython这块文档写得太含糊了...

准备就绪，开始！

在服务器搭好typexo-server

typexo-server@使用方法

配置config.yml

• 将config_template.yml复制重命名为config.yml
• 按照配置文件节配置

Quick Start

准备一个空文件夹 (root_dir)，讲typexo-cli克隆到该文件夹内：

root_dir
└── typexo-cli

初始化项目文件夹：

python3 typexo-cli/main.py init

会产生workplace目录：

root_dir
├── typexo-cli
└── workplace

从生产环境拉取：

python3 main.py pull prod

最终目录结构：

root_dir
├── typexo-cli
│   ├── README
│   ├── README.md
│   ├── cache
│   ├── config.yml
│   ├── config_template.yml
│   ├── imgs
│   ├── lib
│   ├── main.py
│   ├── server
│   └── site
└── workplace
    ├── README.md
    ├── cids-generated.json
    ├── metas.json
    ├── page_drafts
    ├── pages
    ├── post_drafts
    └── posts

关于本地测试服务器

我们的目标之一是能够像Hexo一样能够在本地搭建测试服务器，所以我们同时把typexo-server作为submodule引入了本项目。(这个功能相对独立，和其他部分无关)

实现方法：在本地搭建php服务器和typexo-server.

具体实现细节仍在考虑当中。

命令说明

注：✅代表已完成，❌代表未完成，🚧代表正在编写。

✅ init

初始化workplace。会在当前目录新建一个workplace文件夹，然后在其内部初始化git。

✅ rm

删除workplace。直接删除workplace文件夹，需要操作确认。

✅ commit

相当于对当前分支进行git commit -am，提交代码。

✅ discard-change

相当于对当前分支进行git reset --hard HEAD，会删除所有未提交更改，需要操作确认。

✅ status

相当于对当前分支进行git status，获取当前信息。

✅ merge {prod|test}

先切换到主分支，然后合并输入的分支 ( prod / test )

✅ fix-git-utf8

修复git在命令行中可能对中文产生的乱码现象。等价命令：

git config --global core.quotepath false				# 显示 status 编码
git config --global gui.encoding utf-8					# 图形界面编码
git config --global i18n.commit.encoding utf-8			# 提交信息编码
git config --global i18n.logoutputencoding utf-8		# 输出 log 编码

Reference: http://howiefh.github.io/2014/10/11/git-encoding/

✅ prod-test

对生产环境进行连通性测试。

✅ clone

从远程仓库拉取workplace，需要在config.yml中配置。

✅ pull {prod|test}

从 prod / test 环境导入到本地对应分支，并自动进行merge操作。

✅ push

将 workplace 推送到远程仓库，需要在config.yml中配置。

✅ format

格式化所有markdown文件，即自动对于各种meta进行排序。

✅ new [--draft] {post|page} TITLE

创建新内容。如果使用--draft选项则代表是草稿，TITLE是文章标题。

✅ import [--draft] {post|page} FILE

导入markdown文件。如果使用--draft选项则代表是草稿，FILE是文件路径。

🚧 diff {prod|test}

与远程typexo-server服务器传回的内容进行比对，列出更改 / 删除 / 增加过的项目。

✅ deploy {prod|test}

将内容更改上传到prod / test.

🚧 server

本地搭建test环境，导入sql表，搭建typecho的php-server

配置文件

prod字段

• [只能在 Unix 下使用，用来解决跨时区编辑问题] timezone - 时区。格式：Asia/Shanghai。
• token - 生产环境的typexo-server的验证token
• url - 生产环境typexo-server的访问链接

test字段

• token - 测试环境的typexo-server的验证token
• url - 测试环境typexo-server的访问链接

fields字段

在看这一节之前，请先了解typecho_fields数据库，是存储文章自定义字段的数据库。参考资料：

• typexo-server API
• typecho 数据库设计

由于官方对于自定义字段指定了三种type:

• str
• int
• float

所以一些常用类型，比如说boolean会产生错误。为此，专门设置这个字段来指明各个自定义字段的属性。配置示例：

fields:
  customField1: str
  customField2: int
  customField3: float

defaultFields字段

defaultFields字段的作用就是配置在新建文章的时候，需要默认生成的自定义字段。配置格式：

defaultFields:
  fieldName: fieldValue

注意：对于yes, no, true, false等本身带有特殊含义可以被解析的值而言，请加上引号。

defaultSlugType字段

可选项：cid, title. 指在生成新文章时，默认的slug内容。

repo字段

• url - 远程 git 仓库地址

使用注意事项

不得编辑的文件

• 请勿直接在metas.json内添加新的meta，如果需要添加并更改属性，请使用其他方式，如：直接在浏览器中进行此操作 / 将新meta添加到一篇文章中，在deploy后再在metas.json中进行进行编辑
• 请勿编辑cids-generated.json

可能出现的合并冲突

meta顺序更换问题

由于文章的meta是自动生成的，所以在手动更改之后，可能与自动生成的不一致（比如说tags, categories中的顺序），为此，我们有时需要手动解决conflict。如下图：

我们需要accept incoming change

以cid作为slug的问题

由于slug需要先deploy才能知道，所以拉去下来会出现conflict（因为增加了slug的信息）。在这种情况下，我们需要同时保留本地的更改和新增的slug信息，同时需要注意要按照指定的顺序（否则会出现错误）。如果不想出现这样的情况，那么可以不要以cid作为slug。可以在配置文件中设置。