便捷记账
自动识别账单明细并记录
目标
在手机上完成一笔收支后,通过 OCR 识别交易截图中的文字,并提交大模型解析交易字段明细,确认明细后记入自己的云端服务器。
最终效果
从账单截图提取明细后,快捷指令会打开确认页。核对并提交后,页面显示记账成功。
前提条件
- 支持运行快捷指令的 iPhone。
- 一台可从外网访问的支持docker自有服务器。
- 用于从 OCR 文本中提取交易明细的 DeepSeek API 密钥。
实现思路
- iPhone 快捷指令截取交易页面,通过 OCR 提取文字,然后发送给自建的
expense_api服务。 -
expense_api服务调用 DeepSeek API 提取交易明细,生成确认页面,并把网址返回给快捷指令。 - 快捷指令在浏览器中打开确认页面。用户可以修改明细,确认后交易会写入
Firefly III。
部署流程
1. 部署 Firefly III 记账服务
展开 Firefly III 的 Docker Compose 配置
services:
app:
image: fireflyiii/core:latest
hostname: app
container_name: firefly_iii_core
restart: always
volumes:
- /{somepath}/firefly_iii/firefly_iii_upload:/var/www/html/storage/upload
ports:
- 8080:8080
depends_on:
- db
environment:
# You can leave this on "local". If you change it to production
# most console commands will ask for extra confirmation.
- APP_ENV=production
# Set to true if you want to see debug information.
- APP_DEBUG=false
# Administrator email address
- SITE_OWNER=xxx@example.com
# Encryption key, exactly 32 characters
# head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo
- APP_KEY=xxxxxxxxxxxxxxxxx
# Language settings
- DEFAULT_LANGUAGE=zh_CN
- DEFAULT_LOCALE=zh_CN
# Timezone
- TZ=Asia/Shanghai
# Logging
- LOG_CHANNEL=stack
- APP_LOG_LEVEL=notice
- AUDIT_LOG_LEVEL=emergency
# Database settings
- DB_CONNECTION=mysql
- DB_HOST=192.168.xx.xx
- DB_PORT=3306
- DB_DATABASE=firefly
- DB_USERNAME=firefly
- DB_PASSWORD=fireflyDb,.
# MYSQL_USE_SSL=false
- MYSQL_SSL_VERIFY_SERVER_CERT=true
# You need to set at least of these options
- MYSQL_SSL_CAPATH=/etc/ssl/certs/
- MYSQL_SSL_CA=
- MYSQL_SSL_CERT=
- MYSQL_SSL_KEY=
- MYSQL_SSL_CIPHER=
# Cache & Session
- CACHE_DRIVER=file
- SESSION_DRIVER=file
# Authentication
- AUTHENTICATION_GUARD=web
# Cron token (must be exactly 32 characters)
- STATIC_CRON_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
# Public URL of Firefly III
- APP_URL="https://xxxxxx.xx.xx.xx:8080"
- TRUSTED_PROXIES=**
# Cookie settings. Should not be necessary to change these.
# If you use Docker or similar, you can set COOKIE_DOMAIN_FILE to set
# the value from a file instead of from an environment variable
# Setting samesite to "strict" may give you trouble logging in.
- COOKIE_PATH="/"
- COOKIE_DOMAIN=
- COOKIE_SECURE=false
- COOKIE_SAMESITE=lax
# The map will default to this location:
- MAP_DEFAULT_LAT=51.983333
- MAP_DEFAULT_LONG=5.916667
- MAP_DEFAULT_ZOOM=6
- DISABLE_FRAME_HEADER=false
- DISABLE_CSP_HEADER=false
# Leave the following configuration vars as is.
# Unless you like to tinker and know what you're doing.
- APP_NAME=FireflyIII
- BROADCAST_DRIVER=log
- QUEUE_DRIVER=sync
- CACHE_PREFIX=firefly
- PUSHER_KEY=
- IPINFO_TOKEN=
- PUSHER_SECRET=
- PUSHER_ID=
- DEMO_USERNAME=
- DEMO_PASSWORD=
# The v2 layout is very experimental. If it breaks you get to keep both parts.
# Be wary of data loss.
- FIREFLY_III_LAYOUT=v1
db:
image: mariadb:lts
hostname: db
container_name: firefly_iii_db
restart: always
ports:
- "3306:3306"
volumes:
- /{somepath}/firefly_iii/firefly_iii_db:/var/lib/mysql
environment:
- MYSQL_RANDOM_ROOT_PASSWORD=yes
- MYSQL_USER=firefly
- MYSQL_PASSWORD=fireflyDb,.
- MYSQL_DATABASE=firefly
cron:
#
# To make this work, set STATIC_CRON_TOKEN in your .env file or as an environment variable
# The STATIC_CRON_TOKEN must be *exactly* 32 characters long
# Use this URL for inspiration: https://www.random.org/strings/?num=1&len=32&digits=on&upperalpha=on&loweralpha=on&unique=on&format=html&rnd=new
#
image: alpine
restart: always
container_name: firefly_iii_cron
command: ["sh", "-c", "apk add tzdata && \
(ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
echo \"0 3 * * * wget -qO- http://xxxx:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" \
| crontab - && \
crond -f -L /dev/stdout"]
network_mode: "bridge"
depends_on:
- app
environment:
# Cron token (must be exactly 32 characters)
- STATIC_CRON_TOKEN=xxxxxxxxxxxxxxxxxxxxxx
volumes:
firefly_iii_upload:
firefly_iii_db:
部署提示:修改配置中的令牌和网址,并确认各服务之间网络互通。
启动容器后,在浏览器中访问 https://xxxxxx.xx.xx.xx:8080,按提示完成初始化。
2. 部署 expense-api 记账解析服务
创建个人访问令牌
在 Firefly III 的「远程访问与令牌」中创建并记录个人访问令牌。

获取代码并构建镜像
从远程仓库拉取最新的 expense-api 代码。
git clone https://github.com/SilenceEagle/firefly_iii_expense_api.git
构建 expense-api 镜像。
cd firefly_iii_expense_api
# 构建时注入版本信息:
docker build \
--build-arg BUILD_DATE="$(date +%Y-%m-%d)" \
--build-arg GIT_COMMIT="$(git rev-parse --short HEAD)" \
-t expense-api .
添加服务配置
将以下配置添加到 Firefly III 的 Compose 文件末尾。
展开 expense-api 的 Docker Compose 配置
services:
app:
...
db:
...
cron:
...
expense-api:
image: expense-api:latest
restart: always
container_name: expense-api
ports:
- "8081:8081"
depends_on:
- app
environment:
FIREFLY_URL: http://xxxx:8080
FIREFLY_TOKEN: 这里填firefly III的个人访问令牌
API_KEY: 这里填一个密码,后续用于快捷指令的认证
LLM_API_URL: "https://api.deepseek.com/chat/completions"
LLM_API_KEY: "sk-xxxxxxx"
LLM_MODEL: "deepseek-flash"
volumes:
- /{somepath}/firefly_iii/expose_api/data:/app/data
- /{somepath}/firefly_iii/expose_api/response:/app/response
volumes:
firefly_iii_upload:
firefly_iii_db:
expense-api的详细处理流程可参考githhub仓库
3. 配置 iPhone 快捷指令
可以直接导入记账模板,也可以按下面的步骤手动创建。
- 添加「截屏」和「从截屏提取文本」动作。
- 用「获取 URL 内容」向
https://你的expense-api服务地址/edit发送请求。- 方法选
POST。 - 请求头填
Authorization: Bearer 你的API_KEY。 - 请求体选
JSON,将ocr_text的值设为提取的文本。
- 方法选
- 从返回的「URL 的内容」中读取
edit_id,保存为变量EditID。 - 在「文本」动作中拼接
https://你的expense-api服务地址/edit/和变量EditID,再打开该网址以确认交易明细。
快捷指令截图
4. (可选)自定义Firefly III v6.7.9 的首页
Firefly III的默认首页内容较分散,经查阅发现ezBookkeeping的首页效果比较好,故将Firefly III的首页内容自定义成了这样的效果:

部署:
git clone https://github.com/SilenceEagle/firefly_III_custom_dashboard.git
然后在上述firefly III的 Compose 文件中添加以下配置:
services:
app:
volumes:
- /{some path}/index.blade.php:/var/www/html/resources/views/index.blade.php:ro
- /{some path}/assets:/var/www/html/public/custom-dashboard:ro
然后重新创建容器即可。