📖

Self-Hosted Costflow Hub 使用文档

1. 下载 Costflow Hub 客户端

在购买确认邮件中,点击页面中的「查看内容」按钮即可前往下载页面。在下载页面选择你想要运行Costflow Hub 的系统,点击下载即可。

如果您想在 Linux 服务器上运行,可以直接使用命令行下载:

curl -L https://self-hosted.costflow.io/download/linux --output costflow-hub-linux
sudo chmod 755 ./costflow-hub-linux

测试 Costflow Hub 是否支持您的系统

现在以第 6 步中的命令运行 Costflow Hub,如果程序没有崩溃并且显示了当前版本信息,则代表 Costflow Hub 可以支持您的系统。

2. 获取 License

Gumroad 购买产品后,我们会把 License 发送到您的邮箱。

💡

License 在任何 Costflow Hub 支持的系统中均可使用,但是同时运行的服务只能有一个。

3. 申请 Telegram Bot Token

在电脑或手机客户端登录 Telegram,给官方 bot 机器人 @botfather 发送 /newbot 命令开始创建个人 Bot,然后按照提示输入 name 以及 username 即可。

Token 会在 Bot 创建成功后返回。
Token 会在 Bot 创建成功后返回。

4. 配置 hub.json

在下载的 Costflow Hub 的同一文件夹中,创建一个名为 hub.json 的文件。这个文件可以用来配置 Costflow Hub 表现。

一个简单的 hub.json 内容如下:

{
  "license": "AAAAAAAA-BBBBBBBB-CCCCCCCC-DDDDDDDD",
  "telegram_bot_token": "11111111:AAAAAAABBBBBBBCCCCCCDDDD",
  "authorized_users": {
    "telegram": "leplay"
  },
  "config_path": "",
  "ledger_path": "~/costflow-hub/%YYYY/MM%.bean",
  "proxy": ""
}
💡

注意替换 licensetelegram_bot_token另外为保证 Bot 安全,避免其它人发送的消息记录到您本地的文件,要把 authorized_users.telegram 属性设置为个人的 Telegram usernameconfig_pathcostflow.json 的位置,如果在同一目录则无需填写。 ledger_path 为 Beancount 文件保存路径,支持年月日的变量(使用 % 包裹),例如 %YYYY/MM%.bean 则是在年份目录下每个月份账单记录到同一文件, proxy 是为运行设备不能直连 Telegram 设置的代理,支持 HTTP / HTTPS 代理,例如 https://1.1.1.1:2020

5. 配置 costflow.json

costflow.json 是 Costflow 语法所需的配置。一个简单的配置示例:

{
  "currency": "USD",
  "mode": "beancount",
  "timezone": "Asia/Hong_Kong",
  "tag": "#costflow",
  "indent": 2,
  "lineLength": 50,
  "insertTime": "metadata",
  "alphavantage": "AAAABBBBCCCC",
  "account": {
    "cloud": "Expenses:Tech:Cloud",
    "eob": "Equity:Opening-Balances",
    "spotify": "Expenses:Entertainment:Spotify",
    "visa": "Liabilities:CreditCard:VISA"
  },
  "formula": {
    "aws": "! @AWS {{ amount }} USD visa > cloud",
    "spotify": "! @Spotify 15.98 USD visa > spotify"
  }
}

完整配置说明请参考 Costflow Syntax 文档

6. 运行 Costflow Hub

完成以上配置后,使用命令行 cd 到产品所在目录,然后运行下方命令即可运行 Costflow Hub。

Mac OS

./costflow-hub-macos

Windows

# 需在命令提示符中输入,双击打开无法运行
costflow-hub-win.exe

Linux

./costflow-hub-linux

如果要在远程服务器上,保持 Costflow Hub 的后台运行,可以使用 screen 命令

Syntax 文档

安全建议

  • 不要分享您的 Telegram token 以及 bot 名称/地址,另外请正确设置 authorized_users 字段否则会导致您的机器承受不必要的负载;
  • 如果发现您的 Telegram Bot 被滥用,请尝试重置 Bot Token(@botfather)。如果 Telegram Bot 因暴露 username 被他人攻击,可以考虑新建 Bot(Telegram 目前无法修改 username)。
  • 不要分享您的 License;
  • 如果是在服务器上使用,请确保在 Network 设置或者本机防火墙屏蔽非必要的端口;