受到Hexo
这样的基于nodejs
的,可以本地编辑的博客的启发,typexo
旨在对于typecho
的博客开发类似的功能。本项目typexo-cli
是本地端的实现,用于编辑内容、本地测试、远程部署。
目前本项目仅针对MySQL
数据库进行开发,其他数据库日后会进行支持。
目前本项目不支持typecho
的attachments
, 解决方案是使用自己的图床, 该功能可能会在日后支持(可能性不大)。
请注意:服务端程序会直接对数据库进行操作,如果你不知道程序在干什么,请勿执行。硬盘有价,数据无价。请确保在操作之前对数据库进行备份。
- 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
这块文档写得太含糊了...
- 将
config_template.yml
复制重命名为config.yml
- 按照配置文件节配置
准备一个空文件夹 (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
.
具体实现细节仍在考虑当中。
注:✅代表已完成,❌代表未完成,🚧代表正在编写。
初始化workplace
。会在当前目录新建一个workplace
文件夹,然后在其内部初始化git
。
删除workplace
。直接删除workplace
文件夹,需要操作确认。
相当于对当前分支进行git commit -am
,提交代码。
相当于对当前分支进行git reset --hard HEAD
,会删除所有未提交更改,需要操作确认。
相当于对当前分支进行git status
,获取当前信息。
先切换到主分支,然后合并输入的分支 ( prod
/ test
)
修复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/
对生产环境进行连通性测试。
从远程仓库拉取workplace
,需要在config.yml
中配置。
从 prod
/ test
环境导入到本地对应分支,并自动进行merge
操作。
将 workplace
推送到远程仓库,需要在config.yml
中配置。
格式化所有markdown
文件,即自动对于各种meta
进行排序。
创建新内容。如果使用--draft
选项则代表是草稿,TITLE
是文章标题。
导入markdown文件。如果使用--draft
选项则代表是草稿,FILE
是文件路径。
与远程typexo-server
服务器传回的内容进行比对,列出更改 / 删除 / 增加过的项目。
将内容更改上传到prod
/ test
.
本地搭建test
环境,导入sql
表,搭建typecho
的php-server
- [只能在 Unix 下使用,用来解决跨时区编辑问题]
timezone
- 时区。格式:Asia/Shanghai
。 token
- 生产环境的typexo-server
的验证token
url
- 生产环境typexo-server
的访问链接
token
- 测试环境的typexo-server
的验证token
url
- 测试环境typexo-server
的访问链接
在看这一节之前,请先了解typecho_fields
数据库,是存储文章自定义字段的数据库。参考资料:
由于官方对于自定义字段指定了三种type
:
str
int
float
所以一些常用类型,比如说boolean
会产生错误。为此,专门设置这个字段来指明各个自定义字段的属性。配置示例:
fields:
customField1: str
customField2: int
customField3: float
defaultFields
字段的作用就是配置在新建文章的时候,需要默认生成的自定义字段。配置格式:
defaultFields:
fieldName: fieldValue
注意:对于yes
, no
, true
, false
等本身带有特殊含义可以被解析的值而言,请加上引号。
可选项:cid
, title
. 指在生成新文章时,默认的slug
内容。
url
- 远程git
仓库地址
- 请勿直接在
metas.json
内添加新的meta
,如果需要添加并更改属性,请使用其他方式,如:直接在浏览器中进行此操作 / 将新meta
添加到一篇文章中,在deploy
后再在metas.json
中进行进行编辑 - 请勿编辑
cids-generated.json
由于文章的meta
是自动生成的,所以在手动更改之后,可能与自动生成的不一致(比如说tags
, categories
中的顺序),为此,我们有时需要手动解决conflict
。如下图:
我们需要accept incoming change
由于slug
需要先deploy
才能知道,所以拉去下来会出现conflict
(因为增加了slug
的信息)。在这种情况下,我们需要同时保留本地的更改和新增的slug
信息,同时需要注意要按照指定的顺序(否则会出现错误)。如果不想出现这样的情况,那么可以不要以cid
作为slug
。可以在配置文件中设置。