【免费下载链接】KoffanFree selfhosted groceries list for families and shared households项目地址https://gitcode.com/gh_mirrors/ko/Koffan点击查看免费下载Koffan 是一款免费的自托管self-hosted购物清单应用适合家庭和合租住户共享使用。升级 Koffan 时最大的陷阱藏在数据库里升级到 2.16.0 后数据库会被自动迁移旧版本无法再读写迁移后的历史记录也不存在降级路径——想回滚只能靠升级前备份的数据库文件。本文面向新手完整讲清 Koffan 备份怎么做、升级时数据库迁移改了什么、以及降级问题该如何规避。一、先找到数据库文件备份的对象是它Koffan 的所有数据购物清单、分组、模板、自动补全历史、账户与工作区都保存在一个 SQLite 文件里。找到它备份就有了着落部署方式数据库文件位置Docker推荐容器内/data/shopping.db映射到宿主机卷默认卷名shopping-data或 Quick Start 中的koffan-dataDocker Compose同样挂载到/data见 docker-compose.yaml源码直接运行go run .当前目录下的shopping.db可用环境变量DB_PATH修改数据库路径由环境变量DB_PATH决定默认为./shopping.db读取逻辑见 db/db.goDocker 镜像在构建时已固定为/data/shopping.db见 Dockerfile。一键备份步骤Docker 卷# 1. 停掉 Koffan避免写入到一半 docker stop koffan容器名 # 2. 从数据卷复制出带时间戳的备份 docker run --rm -v shopping-data:/data alpine \ sh -c cp /data/shopping.db /data/shopping.db.bak-$(date %Y%m%d) # 3. 重新启动 docker start koffan容器名⚠️ 先停服务再复制文件是最稳妥的做法。备份完成后确认文件不是 0 字节有条件的话可以多备一份到 NAS 或异地。二、逻辑备份JSON / CSV 导出跨版本的兜底数据库文件备份是恢复的首选但还有一层更人类可读的备份Koffan 内置数据管理功能可以导出整个工作区的 JSON含模板和历史或 CSV。入口打开 Koffan 首页右上角的 ⚙️ 设置 →Data选项卡入口代码在 templates/home.html。Export JSON下载koffan-export-日期.json包含所有清单、模板和自动补全历史文件名与格式定义见 handlers/export.goExport CSV便于用 Excel 查看或做二次分析Import支持把之前导出的 JSON/CSV 导入回来注意两点启用多用户MULTI_USERtrue后导出/导入只作用于当前工作区不是整个数据库JSON 导出是逻辑备份适合做保险丝但账户、会话等信息不在其中——所以升级前请务必先做数据库文件备份。三、2.16.0 的数据库迁移陷阱详解3.1 升级时自动发生什么2.16.0 首次启动会执行迁移无论你是否开启多用户账户迁移入口 db/db.go 中的runMigrations()核心逻辑在 db/workspaces.go新建users、workspaces、workspace_members三张表并预置默认工作区 Home给lists、templates、sessions等表追加workspace_id列让历史数据自动归入 Home重建item_history表自动补全历史从全局唯一变为每个工作区各自独立SQLite 无法原地修改唯一约束只能建新表、搬数据、删旧表。迁移是幂等的正常重启不会重复执行日志中能看到Migration completed字样看到它们说明迁移成功了。3.2 为什么说没有降级路径官方文档README.md 的 Upgrading 一节说得很直接旧版本无法在已迁移的数据库上保存商品历史并且会忽略工作区概念——开着共享密码的实例里任何人登录后将看到所有工作区的清单。翻译成大白话把 2.16.0 跑过之后的数据库换回旧版本程序轻则历史记录悄悄丢失重则隐私问题跨工作区数据全部可见所以回滚唯一正确姿势 停服务 用备份文件还原数据库还原之后升级期间产生的新数据会丢失。这就是迁移陷阱的全部不是数据被删了而是新旧格式互不兼容且只能单向升级。3.3 安全的升级清单 ✅在设置 → Data 中先导出 JSON逻辑备份兜底停止 Koffan复制数据库文件做时间戳备份见上一节的命令拉取新镜像 / 更新源码并启动例如 Docker Quick Start 使用ghcr.io/pansalut/koffan:latest打开应用确认真清单、模板正常日志无Migration failed观察一两周稳定后再删除旧备份。四、从 2.9.x 升级记得端口变了另一个常见的升级坑与数据库无关2.10.0 起容器默认端口从80改为8080镜像改为非 root 用户运行80 属于特权端口。如果你从 2.9.x 直接升级需要同步修改端口映射和反向代理原来改为docker run -p 80:80docker run -p 80:8080docker run -p 3000:80docker run -p 3000:8080反向代理nginx/Caddy/Traefikupstream 指向80指向8080如果你之前是靠覆盖PORT环境变量绕过特权端口问题现在可以直接去掉该覆盖。读取镜像EXPOSE的自动部署平台如 Coolify会在重新部署时自动使用新端口。五、常见问题速查场景建议只升小版本未跨 2.16.0正常升级即可迁移是幂等的可不动数据跨 2.16.0 升级必须先备份数据库文件 导出 JSON再升级升级后想回旧版本停止服务 → 用备份文件覆盖数据库 → 启动。升级期间的新数据会丢开启MULTI_USER之前同样先备份数据库READMETurning accounts on 第 1 步即要求备份忘记密码想清账户备份后按 README Forgotten administrator password 一节操作六、总结与相关文件升级前永远先备份一个 SQLite 文件 一份 JSON 导出双保险2.16.0 的迁移单向不可逆降级 还原备份文件没有自动回滚这回事从 2.9.x 升上来时别忘端口80 → 8080。文件说明README.md官方升级注意事项Upgrading / Docker 一节db/db.go数据库初始化与迁移调度runMigrations()db/workspaces.go2.16.0 工作区与历史表重建迁移handlers/export.goJSON/CSV 导出实现docker-compose.yaml / docker-compose.local.yaml数据卷/data与DB_PATH配置VERSION当前版本号按照这份清单操作升级 Koffan 就能做到随时敢升、随时能退。赞分享【免费下载链接】KoffanFree selfhosted groceries list for families and shared households项目地址https://gitcode.com/gh_mirrors/ko/Koffan点击查看免费下载相关推荐Roundcube Webmail 升级指南从备份到数据库迁移的完整流程Roundcube Webmail 升级指南从备份到数据库迁移的完整流程 前言 Roundcube Webmail 作为一款广泛使用的开源网页邮件客户端其版后端前端企业应用Prisma 服务升级指南发布说明、数据备份与分版本迁移全流程Prisma 服务升级指南发布说明、数据备份与分版本迁移全流程 导读 升级 Prisma Server 不是简单的镜像替换而是一个涉及配置迁移、数据安全与回后端数据库GraphQLPot 划词翻译保姆级教程从安装到截图翻译、本地接口调用Pot 划词翻译保姆级教程从安装到截图翻译、本地接口调用 在网页里选中一段外文按一下快捷键译文立刻浮现在光标旁边。这就是 Pot 划词翻译的日常打开方式。桌面应用OCRAI 应用上一篇OpenPencil copywriting 技能拆解AI 生成界面中的文案压缩规则与工程调度下一篇5 分钟上手 MCP Adapter从零安装到暴露你的第一个 WordPress 能力创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/27 10:14:37 · 阅读 1.2k Koffan备份与升级指南：数据库迁移陷阱与降级问题的完整说明
【免费下载链接】KoffanFree selfhosted groceries list for families and shared households项目地址https://gitcode.com/gh_mirrors/ko/Koffan点击查看免费下载Koffan 是一款免费的自托管self-hosted购物清单应用适合家庭和合租住户共享使用。升级 Koffan 时最大的陷阱藏在数据库里升级到 2.16.0 后数据库会被自动迁移旧版本无法再读写迁移后的历史记录也不存在降级路径——想回滚只能靠升级前备份的数据库文件。本文面向新手完整讲清 Koffan 备份怎么做、升级时数据库迁移改了什么、以及降级问题该如何规避。一、先找到数据库文件备份的对象是它Koffan 的所有数据购物清单、分组、模板、自动补全历史、账户与工作区都保存在一个 SQLite 文件里。找到它备份就有了着落部署方式数据库文件位置Docker推荐容器内/data/shopping.db映射到宿主机卷默认卷名shopping-data或 Quick Start 中的koffan-dataDocker Compose同样挂载到/data见 docker-compose.yaml源码直接运行go run .当前目录下的shopping.db可用环境变量DB_PATH修改数据库路径由环境变量DB_PATH决定默认为./shopping.db读取逻辑见 db/db.goDocker 镜像在构建时已固定为/data/shopping.db见 Dockerfile。一键备份步骤Docker 卷# 1. 停掉 Koffan避免写入到一半 docker stop koffan容器名 # 2. 从数据卷复制出带时间戳的备份 docker run --rm -v shopping-data:/data alpine \ sh -c cp /data/shopping.db /data/shopping.db.bak-$(date %Y%m%d) # 3. 重新启动 docker start koffan容器名⚠️ 先停服务再复制文件是最稳妥的做法。备份完成后确认文件不是 0 字节有条件的话可以多备一份到 NAS 或异地。二、逻辑备份JSON / CSV 导出跨版本的兜底数据库文件备份是恢复的首选但还有一层更人类可读的备份Koffan 内置数据管理功能可以导出整个工作区的 JSON含模板和历史或 CSV。入口打开 Koffan 首页右上角的 ⚙️ 设置 →Data选项卡入口代码在 templates/home.html。Export JSON下载koffan-export-日期.json包含所有清单、模板和自动补全历史文件名与格式定义见 handlers/export.goExport CSV便于用 Excel 查看或做二次分析Import支持把之前导出的 JSON/CSV 导入回来注意两点启用多用户MULTI_USERtrue后导出/导入只作用于当前工作区不是整个数据库JSON 导出是逻辑备份适合做保险丝但账户、会话等信息不在其中——所以升级前请务必先做数据库文件备份。三、2.16.0 的数据库迁移陷阱详解3.1 升级时自动发生什么2.16.0 首次启动会执行迁移无论你是否开启多用户账户迁移入口 db/db.go 中的runMigrations()核心逻辑在 db/workspaces.go新建users、workspaces、workspace_members三张表并预置默认工作区 Home给lists、templates、sessions等表追加workspace_id列让历史数据自动归入 Home重建item_history表自动补全历史从全局唯一变为每个工作区各自独立SQLite 无法原地修改唯一约束只能建新表、搬数据、删旧表。迁移是幂等的正常重启不会重复执行日志中能看到Migration completed字样看到它们说明迁移成功了。3.2 为什么说没有降级路径官方文档README.md 的 Upgrading 一节说得很直接旧版本无法在已迁移的数据库上保存商品历史并且会忽略工作区概念——开着共享密码的实例里任何人登录后将看到所有工作区的清单。翻译成大白话把 2.16.0 跑过之后的数据库换回旧版本程序轻则历史记录悄悄丢失重则隐私问题跨工作区数据全部可见所以回滚唯一正确姿势 停服务 用备份文件还原数据库还原之后升级期间产生的新数据会丢失。这就是迁移陷阱的全部不是数据被删了而是新旧格式互不兼容且只能单向升级。3.3 安全的升级清单 ✅在设置 → Data 中先导出 JSON逻辑备份兜底停止 Koffan复制数据库文件做时间戳备份见上一节的命令拉取新镜像 / 更新源码并启动例如 Docker Quick Start 使用ghcr.io/pansalut/koffan:latest打开应用确认真清单、模板正常日志无Migration failed观察一两周稳定后再删除旧备份。四、从 2.9.x 升级记得端口变了另一个常见的升级坑与数据库无关2.10.0 起容器默认端口从80改为8080镜像改为非 root 用户运行80 属于特权端口。如果你从 2.9.x 直接升级需要同步修改端口映射和反向代理原来改为docker run -p 80:80docker run -p 80:8080docker run -p 3000:80docker run -p 3000:8080反向代理nginx/Caddy/Traefikupstream 指向80指向8080如果你之前是靠覆盖PORT环境变量绕过特权端口问题现在可以直接去掉该覆盖。读取镜像EXPOSE的自动部署平台如 Coolify会在重新部署时自动使用新端口。五、常见问题速查场景建议只升小版本未跨 2.16.0正常升级即可迁移是幂等的可不动数据跨 2.16.0 升级必须先备份数据库文件 导出 JSON再升级升级后想回旧版本停止服务 → 用备份文件覆盖数据库 → 启动。升级期间的新数据会丢开启MULTI_USER之前同样先备份数据库READMETurning accounts on 第 1 步即要求备份忘记密码想清账户备份后按 README Forgotten administrator password 一节操作六、总结与相关文件升级前永远先备份一个 SQLite 文件 一份 JSON 导出双保险2.16.0 的迁移单向不可逆降级 还原备份文件没有自动回滚这回事从 2.9.x 升上来时别忘端口80 → 8080。文件说明README.md官方升级注意事项Upgrading / Docker 一节db/db.go数据库初始化与迁移调度runMigrations()db/workspaces.go2.16.0 工作区与历史表重建迁移handlers/export.goJSON/CSV 导出实现docker-compose.yaml / docker-compose.local.yaml数据卷/data与DB_PATH配置VERSION当前版本号按照这份清单操作升级 Koffan 就能做到随时敢升、随时能退。赞分享【免费下载链接】KoffanFree selfhosted groceries list for families and shared households项目地址https://gitcode.com/gh_mirrors/ko/Koffan点击查看免费下载相关推荐Roundcube Webmail 升级指南从备份到数据库迁移的完整流程Roundcube Webmail 升级指南从备份到数据库迁移的完整流程 前言 Roundcube Webmail 作为一款广泛使用的开源网页邮件客户端其版后端前端企业应用Prisma 服务升级指南发布说明、数据备份与分版本迁移全流程Prisma 服务升级指南发布说明、数据备份与分版本迁移全流程 导读 升级 Prisma Server 不是简单的镜像替换而是一个涉及配置迁移、数据安全与回后端数据库GraphQLPot 划词翻译保姆级教程从安装到截图翻译、本地接口调用Pot 划词翻译保姆级教程从安装到截图翻译、本地接口调用 在网页里选中一段外文按一下快捷键译文立刻浮现在光标旁边。这就是 Pot 划词翻译的日常打开方式。桌面应用OCRAI 应用上一篇OpenPencil copywriting 技能拆解AI 生成界面中的文案压缩规则与工程调度下一篇5 分钟上手 MCP Adapter从零安装到暴露你的第一个 WordPress 能力创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考