做手工这事儿最磨人的往往不是手艺本身而是“创作过程的管理”。灵感记在手机备忘录里下次找要翻半天材料买了一堆真要用的时候死活想不起来放在哪做到一半的作品拍了几张照片过两个星期连当时怎么想的都忘了。为了解决我自己这个“创作管理混乱症”我花了大半个月做了一个自托管的工作台取名叫 artcraft。它是一个专门为艺术创作和手工制作场景设计的项目管理工具可以把灵感收集、素材库存、项目进度、成品归档全部放进同一个小面板里。这篇文章不是产品发布稿就是一次完整的复盘我会把从需求梳理到部署上线的全过程写清楚包括每个模块为什么这么设计、代码大概怎么组织以及实际运行中踩过的坑希望对同样在折腾创作工具的人有点参考价值。1. 项目整体设计与需求拆解动手写代码之前我先花了不少时间做需求梳理。越梳理越发现一个问题市面上现成的项目管理工具其实非常多但它们几乎都是给“软件研发”或“商业协作”设计的像什么冲刺、迭代、任务指派、燃尽图对手工艺场景来说太重也太不贴肉。1.1 到底解决什么问题我观察自己和几位同样在做创作的朋友发现大家的工作流高度相似基本卡在四个环节上灵感收集看到一张配色舒服的照片、一个纹理好看的材质、一段关于技法的描述随手存下来但散落在相册、备忘录、浏览器收藏夹里。材料管理布料、颜料、木材、金属件、纸张、胶水种类杂不说剩下的量也记不清楚经常买了重复的东西。过程记录手工制作周期长中间有很多阶段性状态需要拍照、写备注、记参数传统文档工具很难形成一个连续的时间线。成品归档作品做完之后拍个照就算了时间一长找不到对应型号、配比参数、工艺步骤想复刻也变得很麻烦。所以 artcraft 最初的需求定义很简单一个能自部署的网页应用围绕“灵感—材料—项目—归档”四个维度来组织数据。它不需要多复杂但要足够顺手打开就能记录不用等云服务同步更不用担心平台哪天关停。1.2 适合谁用不适合谁用在写功能清单之前我要先给这个工具划出一条边界。它适合以下人群独立手工艺人、陶艺师、木工、皮具制作者、面料拼贴创作者美术老师、设计专业学生需要整理教学过程和创作过程的人有轻度库存管理需求的小型个人工作室喜欢数据掌握在自己手里、不喜欢把作品照片传到第三方平台的人。不适合的人群我也得直说如果你是一个多人团队需要复杂的权限审批、自动化工作流或者需要精细到每个小时的项目排期artcraft 并不是替你解决的问题。它的定位是个人创作库而不是全流程的项目管理平台。这也解释了为什么我在技术选型上会倾向简单、好部署、低维护成本的方向。1.3 为什么叫 artcraft名字是把 art 和 craft 组合在一起意思也浅白把艺术感art和手作感craft放在同一个工具里。我不太喜欢把它定位成一个“管理系统”因为“管”这个词太冷好像要约束创作一样。我更愿意把它看作一个陪伴创作过程的工作台。它既要能承载艺术式的自由记录又要能支撑工艺式的反复试验。用这个名字还有一个原因项目本身也是我练手的一个作品。我希望它的气质不要像流水线软件而是像手工工作室里的一本总账本朴素的、耐用的、能长期积累的。后面所有设计决定其实都在往这个方向靠。2. 技术栈选型与架构思路这一章重点说选型因为这决定了一个自托管工具是“装完就不管”还是“三天两头要救火”。我在一开始就定下了几条原则能够本地跑依赖要少升级要方便备份要简单。2.1 为什么用 Python Flask 而不是更重的框架后端我选了 Python 和 Flask。很多人可能会问为什么不直接用 Node.js 或 Go这里没有谁比谁绝对高级而是要看维护成本。Flask 的优点是结构直观简洁单个文件就能启动一个完整服务生态成熟SQLite 配合它非常顺。更重要的一点是这种工具型应用的业务逻辑不复杂不需要 Django 那样的全家桶也不需要 GraphQL 之类的东西。轻量框架写起来快后续改起来也清楚。当然Flask 也有自己的弱点比如默认没有很好的异步支持但在这个场景里完全够用。因为我们处理的都是低频请求一个人使用的时候并发量本来就不高核心瓶颈不在框架而在功能设计是否顺手。2.2 数据存储与文件方案数据分两块结构化数据和图片文件。结构化数据我直接用了 SQLite。有人一听 SQLite 就觉得是玩具其实对于单机自托管场景它反而比 PostgreSQL 更合适。理由有三点第一零配置文件初始化数据库就一行命令第二备份非常方便整个库就是一个文件第三对一台机器上的日常读写SQLite 的性能完全不会成为瓶颈。图片文件我采用了本地磁盘存储的方案。所有上传的图片统一放进一个 uploads 目录数据库里只保存相对路径。这样做的好处是文件系统操作直观而且将来如果要迁移只需要把整个 data 目录打包带走即可。最开始我也考虑过对象存储但对个人自托管来说引入外部依赖不符合“简单可靠”的原则。2.3 前端服务端渲染加少量原生 JavaScript前端我用的是 Flask 自带的 Jinja2 模板加上一点原生 JavaScript。没有引入 Vue、React 这类框架。原因很简单页面数量少、交互也不复杂引入前端框架意味着引入 Node.js 构建链、依赖安装、打包流程这些对于一个个人维护的项目来说是净成本。当然原生 JS 写起来确实不够“现代”但在一个只有灵感板、项目列表、库存表格几个页面的应用里我可以用不到 200 行代码就实现所有需要的交互效果。代码少了出 bug 的地方也就少了。这也是我一直在提醒自己的工具型项目稳定好用比技术新潮更重要。2.4 整体部署形态部署上我把服务拆成两个部分Python 进程负责提供页面和 APINginx 负责转发请求以及托管上传的静态图片文件。我会在后面详细展开具体的部署步骤。整体结构可以理解为Python/Flask 进程监听本地端口比如 127.0.0.1:8000Nginx监听 80/443 端口把 / 下的请求转发给 Python 进程数据目录项目根目录下的 data 文件夹里面包含 SQLite 数据库和 uploads 图片目录。这个结构我经过多次调整现在运行起来基本能做到“即拷即用”拿到一个备份压缩包解压到新机器上启动服务和数据库就全都回来了。3. 核心模块设计与实现细节需求拆完之后我根据实际使用场景把功能切成四个模块灵感板、项目看板、材料库存、作品归档。这四个模块各自独立又通过“项目”这个核心实体串成一条完整的创作链路。下面逐个说设计思路和关键实现。3.1 灵感板收集而不是收藏灵感板的功能表面上很简单就是让你添加图片、链接、文字描述。但我在设计的时候刻意做了一个区分“收藏”是存到角落让它吃灰“收集”是存下来之后还要随时能翻出来刺激自己。所以灵感板不能只是一个静态列表每一条灵感都必须能被关联到一个或多个项目。简单来说我在创建灵感条目的时候会加一个“关联项目”的字段如果不确定具体要挂到哪个项目也可以先放在“未分类”里。后面做项目的时候再回过来把灵感挂过去。这一步设计非常有用因为创作最怕的不是没灵感而是灵感来了之后孤零零地待着没有生根发芽的土壤。我实现的核心模型大致是这样的class Inspiration(db.Model): id db.Column(db.Integer, primary_keyTrue) title db.Column(db.String(200)) image_path db.Column(db.String(255)) link_url db.Column(db.String(500)) note db.Column(db.Text) project_id db.Column(db.Integer, db.ForeignKey(project.id), nullableTrue) created_at db.Column(db.DateTime, defaultdatetime.utcnow)页面模板上我用卡片流的方式展示灵感。每张卡片显示图片或链接标题下面有一行小字标注“已关联项目”或“未分类”。在卡片上直接放两个操作按钮“编辑备注”和“关联项目”。没有多余的信息也没有拖拽排序这些花哨功能。实际用下来越简单的交互越容易坚持使用。3.2 项目看板一条作品的生命周期项目是 artcraft 的核心实体。一个项目对应一个具体作品比如“一把胡桃木书签”、“一幅蓝染挂布”、“一只手工陶杯”。我设计了五个阶段构思、材料准备、制作中、收尾、完成。老实说我在最初版本里用了六七个状态但后来发现状态太多反而让人不知道当前是什么阶段果断收敛成这五个。项目卡片上需要展示的信息包括项目名、封面图、当前状态、开始日期、目标完成日期、最近更新记录。其中“最近更新记录”非常关键它是靠每次记录进度时的时间戳自动反推的。有了这个字段项目列表天然会按活跃度排序正在进行的项目自动排到前面很久没动的项目沉到底部非常符合实际工作习惯。项目状态切换的接口我写得比较简单app.route(/project/int:pid/status, methods[POST]) def update_project_status(pid): project Project.query.get_or_404(pid) new_status request.form.get(status) if new_status in valid_statuses: project.status new_status db.session.commit() record_activity(project.id, 状态变更, f状态更新为: {new_status}) return redirect(url_for(project_detail, pidpid))所有状态切换都会写入活动日志。这个日志模块在后期排查问题的时候帮了我大忙比如某个项目突然看起来不对一查活动记录就能看到是哪天改了状态、传了哪张图。3.3 材料与工具库存名字里就带着数量材料管理模块最让我纠结因为每个人做的东西不一样用到的材料千差万别。有的人是织布用线用量要精确到克有的人是木工需要记录板材尺寸有的人是做首饰材料都是小零件按“个”计数。如果设计成一套固定的字段必然有人不适用。所以我在设计上采用了“通用分类 自定义备注”的方案。每条材料记录包含名称、类别、单位、现有数量、安全库存线和位置。其中“位置”字段是后来才加的起因是我找一卷胶带找了半小时最后发现就在手边工具箱里。自那以后我要求自己做库存时必须填写存放位置。材料的出入库操作我做成一个简单的流水账“入库”操作会新增一条入库记录并增加对应数量“领用”操作会减少对应数量并关联到具体项目这样可以看到每个项目消耗了多少材料当现有数量低于安全库存线时库存列表里会出现醒目标记。这个小功能从一开始的“可有可无”变成了我日常打开频率最高的页面。因为它直接决定了我要不要出门补货也避免了我重复购买那些其实家里还有存货的颜料。3.4 进度记录与作品归档进度记录是使用频率最高的功能。每完成一个小阶段我就会给作品拍一张照片写一两句话。这些记录按时间轴顺序排列构成一个非常直观的制作过程。对创作者来说这个时间轴不仅方便回溯还有另一个作用当你想知道自己“究竟有没有进步”时把几个完整项目的时间轴放在一起看高下立判。实现上进度记录复用了一个统一的“活动记录”机制class Activity(db.Model): id db.Column(db.Integer, primary_keyTrue) project_id db.Column(db.Integer, db.ForeignKey(project.id)) category db.Column(db.String(50)) # note, photo, status content db.Column(db.Text) image_path db.Column(db.String(255)) created_at db.Column(db.DateTime, defaultdatetime.utcnow)作品归档更简单当项目状态变成“完成”后系统会提示补充最终成品图、用料清单配方、工艺总结。这些补充信息平时可不填但一旦填了项目页面就变成了一份可复现的工艺记录。我自己做过一次复刻看着当时留下的参数记录比看图凭记忆乱猜要轻松太多。4. 本地部署与配置实操这一章我给出完整的部署步骤。我的部署环境是 Ubuntu 系统但整个过程在 Debian、Raspberry Pi OS 这类系统上也都适用。为了避免歧义下面所有路径都按/home/www-data/artcraft来算实际部署的时候替换成你自己的目录就好。4.1 环境准备与依赖安装首先确认 Python 版本推荐使用 Python 3.9 以上。然后安装 git 和 pipsudo apt update sudo apt install -y python3 python3-venv python3-pip git nginx mkdir -p /home/www-data cd /home/www-data git clone https://example.com/your-repo/artcraft.git cd artcraft python3 -m venv venv source venv/bin/activate pip install -r requirements.txtrequirements.txt 里的核心依赖并不多我整理下来就这几个Flask3.0.0 Werkzeug3.0.1 gunicorn21.2.0如果是在局域网内自己一个人用gunicorn 也可以不装直接flask run --host0.0.0.0就能跑起来。但如果你打算用 Nginx 做反代并且想让服务在后台持续运行gunicorn 是更规范的选择。4.2 初始化数据库与目录结构依赖装好之后先初始化数据库。我在项目里放了一个init_db.py脚本它会自动完成建表工作source venv/bin/activate python init_db.py初始化完成后项目目录下会出现data文件夹里面包含artcraft.db数据库文件和uploads图片目录。这个data目录是整个项目的核心存档后面做的所有备份都是围绕它来的。接着先生成一把签名密钥我用 openssl 生成随机字符串存放到.env文件里面echo SECRET_KEY$(openssl rand -hex 32) .env这个密钥的作用是给登录会话加密不设置的话每次重启进程用户登录态就会失效。4.3 配置 gunicorn 与开机自启用 gunicorn 启动服务前先确认能正常启动。在 artcraft 目录下执行gunicorn -w 2 -b 127.0.0.1:8000 app:app看到启动日志没有报错之后按下 CtrlC 停止然后把它注册成 systemd 服务。在/etc/systemd/system/artcraft.service里写[Unit] Descriptionartcraft service Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/home/www-data/artcraft EnvironmentFile/home/www-data/artcraft/.env ExecStart/home/www-data/artcraft/venv/bin/gunicorn -w 2 -b 127.0.0.1:8000 app:app Restartalways [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable artcraft sudo systemctl start artcraft这里有个小提醒Userwww-data是因为后面 Nginx 也要以这个用户读取图片文件同用户能避免一堆权限问题。4.4 Nginx 反向代理配置最后一步是配置 Nginx。在/etc/nginx/sites-available/artcraft里写server { listen 80; server_name your_domain_or_ip; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /uploads/ { alias /home/www-data/artcraft/data/uploads/; } }这里client_max_body_size 20m是必须的Nginx 默认只允许 1MB 的上传请求如果你要传手机拍的照片1MB 是完全不够用的。设置完成之后启用配置并重载sudo ln -s /etc/nginx/sites-available/artcraft /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx部署完成之后浏览器打开服务器地址看到的应该是 artcraft 的登录首页。默认账号是安装过程生成的随机密码第一次登录后建议立刻在设置里替换掉。5. 常见问题与排查技巧实录自托管应用最让人头疼的就是出问题没人帮忙所有坑都得自己填。这里我把运行几个月来实际遇到的几个高发问题整理出来并附上我的排查过程。5.1 图片上传失败因为我在设置里限制了上传大小为 20MB所以超过这个限制的图片直接被 Nginx 拒掉页面报 413 错误。这个属于预期行为不算 bug。真正的问题是为什么明明没超过 20MB 还是上传失败后来排查发现是 gunicorn 的超时设置问题。如果用户上传一张大图中间处理时间超过 gunicorn 默认的 30 秒进程就会强行中断。解决办法是在 systemd 里给 gunicorn 加上超时参数ExecStart/home/www-data/artcraft/venv/bin/gunicorn -w 2 -t 120 -b 127.0.0.1:8000 app:app另外如果你用手机通过局域网访问并上传图片Wi-Fi 信号不好、网络波动也会导致上传中断。这个不属于系统问题但会频繁出现建议在弱网环境里先压缩图片再传。5.2 SQLite 数据库被锁我用 SQLite 的时候已经做好了心理准备但第一次真正碰到database is locked错误时还是愣了一下。原因在于 gunicorn 开了 2 个 worker 进程理论上还是有极小概率出现并发写入冲突特别是在一次请求里同时触发了状态更新和文件重命名。排查之后我做了两件事。第一在 Flask 的数据库连接配置里设置timeout20让微观的锁等待时间更宽松。第二把需要写数据库的高频操作都收敛到同一个请求上下文里减少并发写。设置方法如下import sqlite3 from flask import Flask app Flask(__name__) app.config[SQLALCHEMY_ENGINE_OPTIONS] { connect_args: {timeout: 20} }实际运行下来锁问题从每月偶发一次变成了几乎碰不到。5.3 备份与恢复流程备份做得不够早是我最实际的一条教训。第一版代码写完之后我光顾着测试功能完全忘了备份这回事。后来某次操作失误把数据库表清掉了靠着残存的一份旧备份才把数据找回来从那以后我专门写了一个备份脚本。我目前的备份策略是每天凌晨 3 点跑一次 cron把data目录打包然后同步到另外一台局域网机器上。脚本非常简单只有三行tar -czf /backup/artcraft_$(date \%F).tar.gz /home/www-data/artcraft/data find /backup -name artcraft_*.tar.gz -mtime 14 -delete第一条命令生成压缩包第二条命令自动删除 14 天前的旧备份防止磁盘被撑爆。恢复就更简单了把压缩包解压回去覆盖 data 目录再重启服务就可以。5.4 浏览器缓存导致样式不更新还有一个容易被忽略的问题。前端改版之后服务器已经部署了新文件但浏览器还在用旧缓存页面看起来像没更新一样。这个不算 bug但特别糟心。常规做法是在模板文件或静态文件引用路径后面加版本号。我的做法是在 Jinja2 模板里给 CSS 文件的引用手动加一个时间戳参数link relstylesheet href{{ url_for(static, filenamestyle.css) }}?v{{ version }}然后每次改完前端就给全局变量version加一。这样改完之后浏览器会强制拉取新文件同时不影响常规缓存效率。6. 后续演进方向与个人心得artcraft 做到目前这个程度基本已经让我自己的创作过程顺畅很多。但说实话技术永远是手段这个项目让我最有收获的地方其实是对自己创作习惯的重新梳理。6.1 使用习惯决定工具价值我发现一个特别普遍的现象工具做得再好如果你不持续往里面填充有效信息它就是一堆空表格。反过来哪怕工具稍微简陋一点只要形成了“完成一个阶段就顺手记录一下”的习惯它积累出的数据会很惊人。我个人的建议是不要等到作品完成才一次性补进度记录而是每完成一个小步骤或者遇到想要记住的细节就立即写一句话、拍一张照片。后面回看的时候那些随手记下的碎片反而是最真实也最有价值的部分。另一个我始终坚持的习惯是给每个项目维护“决策记录”。比如某件木工作品我会顺手写一笔“这次没用樱桃木而用了黑胡桃因为客户要求更深的颜色”这种记录在做系列作品时特别管用。它不需要占用多少时间但会让每个项目都留下可以复用的经验。6.2 值得继续扩展的几个方向artcraft 后续还有不少可扩展的点我目前排了几个优先级比较高的标签系统现在“项目—材料—灵感”之间的关联还不够灵活加上标签之后可以做更细致的检索统计视图统计每个材料的使用趋势对成本控制很有帮助多用户支持后面如果要给工作室团队用就需要加入用户权限体系这也是目前代码架构限制比较大的地方二维码标签打印给存放材料的箱子打印带二维码的标签手机扫码就能看到这个位置放了什么东西这个想法我很想实现。扩展方向是无限的但核心原则不变保持简单、保持数据可控、保持作者本人能长期维护。这三点做到了工具自然会越用越顺手。如果你也想折腾类似的自托管创作工具希望这篇复盘能给你一些参考。去写代码之前先花点时间想清楚自己的工作流这个时间投入绝对值得。
做手工这事儿最磨人的往往不是手艺本身而是“创作过程的管理”。灵感记在手机备忘录里下次找要翻半天材料买了一堆真要用的时候死活想不起来放在哪做到一半的作品拍了几张照片过两个星期连当时怎么想的都忘了。为了解决我自己这个“创作管理混乱症”我花了大半个月做了一个自托管的工作台取名叫 artcraft。它是一个专门为艺术创作和手工制作场景设计的项目管理工具可以把灵感收集、素材库存、项目进度、成品归档全部放进同一个小面板里。这篇文章不是产品发布稿就是一次完整的复盘我会把从需求梳理到部署上线的全过程写清楚包括每个模块为什么这么设计、代码大概怎么组织以及实际运行中踩过的坑希望对同样在折腾创作工具的人有点参考价值。1. 项目整体设计与需求拆解动手写代码之前我先花了不少时间做需求梳理。越梳理越发现一个问题市面上现成的项目管理工具其实非常多但它们几乎都是给“软件研发”或“商业协作”设计的像什么冲刺、迭代、任务指派、燃尽图对手工艺场景来说太重也太不贴肉。1.1 到底解决什么问题我观察自己和几位同样在做创作的朋友发现大家的工作流高度相似基本卡在四个环节上灵感收集看到一张配色舒服的照片、一个纹理好看的材质、一段关于技法的描述随手存下来但散落在相册、备忘录、浏览器收藏夹里。材料管理布料、颜料、木材、金属件、纸张、胶水种类杂不说剩下的量也记不清楚经常买了重复的东西。过程记录手工制作周期长中间有很多阶段性状态需要拍照、写备注、记参数传统文档工具很难形成一个连续的时间线。成品归档作品做完之后拍个照就算了时间一长找不到对应型号、配比参数、工艺步骤想复刻也变得很麻烦。所以 artcraft 最初的需求定义很简单一个能自部署的网页应用围绕“灵感—材料—项目—归档”四个维度来组织数据。它不需要多复杂但要足够顺手打开就能记录不用等云服务同步更不用担心平台哪天关停。1.2 适合谁用不适合谁用在写功能清单之前我要先给这个工具划出一条边界。它适合以下人群独立手工艺人、陶艺师、木工、皮具制作者、面料拼贴创作者美术老师、设计专业学生需要整理教学过程和创作过程的人有轻度库存管理需求的小型个人工作室喜欢数据掌握在自己手里、不喜欢把作品照片传到第三方平台的人。不适合的人群我也得直说如果你是一个多人团队需要复杂的权限审批、自动化工作流或者需要精细到每个小时的项目排期artcraft 并不是替你解决的问题。它的定位是个人创作库而不是全流程的项目管理平台。这也解释了为什么我在技术选型上会倾向简单、好部署、低维护成本的方向。1.3 为什么叫 artcraft名字是把 art 和 craft 组合在一起意思也浅白把艺术感art和手作感craft放在同一个工具里。我不太喜欢把它定位成一个“管理系统”因为“管”这个词太冷好像要约束创作一样。我更愿意把它看作一个陪伴创作过程的工作台。它既要能承载艺术式的自由记录又要能支撑工艺式的反复试验。用这个名字还有一个原因项目本身也是我练手的一个作品。我希望它的气质不要像流水线软件而是像手工工作室里的一本总账本朴素的、耐用的、能长期积累的。后面所有设计决定其实都在往这个方向靠。2. 技术栈选型与架构思路这一章重点说选型因为这决定了一个自托管工具是“装完就不管”还是“三天两头要救火”。我在一开始就定下了几条原则能够本地跑依赖要少升级要方便备份要简单。2.1 为什么用 Python Flask 而不是更重的框架后端我选了 Python 和 Flask。很多人可能会问为什么不直接用 Node.js 或 Go这里没有谁比谁绝对高级而是要看维护成本。Flask 的优点是结构直观简洁单个文件就能启动一个完整服务生态成熟SQLite 配合它非常顺。更重要的一点是这种工具型应用的业务逻辑不复杂不需要 Django 那样的全家桶也不需要 GraphQL 之类的东西。轻量框架写起来快后续改起来也清楚。当然Flask 也有自己的弱点比如默认没有很好的异步支持但在这个场景里完全够用。因为我们处理的都是低频请求一个人使用的时候并发量本来就不高核心瓶颈不在框架而在功能设计是否顺手。2.2 数据存储与文件方案数据分两块结构化数据和图片文件。结构化数据我直接用了 SQLite。有人一听 SQLite 就觉得是玩具其实对于单机自托管场景它反而比 PostgreSQL 更合适。理由有三点第一零配置文件初始化数据库就一行命令第二备份非常方便整个库就是一个文件第三对一台机器上的日常读写SQLite 的性能完全不会成为瓶颈。图片文件我采用了本地磁盘存储的方案。所有上传的图片统一放进一个 uploads 目录数据库里只保存相对路径。这样做的好处是文件系统操作直观而且将来如果要迁移只需要把整个 data 目录打包带走即可。最开始我也考虑过对象存储但对个人自托管来说引入外部依赖不符合“简单可靠”的原则。2.3 前端服务端渲染加少量原生 JavaScript前端我用的是 Flask 自带的 Jinja2 模板加上一点原生 JavaScript。没有引入 Vue、React 这类框架。原因很简单页面数量少、交互也不复杂引入前端框架意味着引入 Node.js 构建链、依赖安装、打包流程这些对于一个个人维护的项目来说是净成本。当然原生 JS 写起来确实不够“现代”但在一个只有灵感板、项目列表、库存表格几个页面的应用里我可以用不到 200 行代码就实现所有需要的交互效果。代码少了出 bug 的地方也就少了。这也是我一直在提醒自己的工具型项目稳定好用比技术新潮更重要。2.4 整体部署形态部署上我把服务拆成两个部分Python 进程负责提供页面和 APINginx 负责转发请求以及托管上传的静态图片文件。我会在后面详细展开具体的部署步骤。整体结构可以理解为Python/Flask 进程监听本地端口比如 127.0.0.1:8000Nginx监听 80/443 端口把 / 下的请求转发给 Python 进程数据目录项目根目录下的 data 文件夹里面包含 SQLite 数据库和 uploads 图片目录。这个结构我经过多次调整现在运行起来基本能做到“即拷即用”拿到一个备份压缩包解压到新机器上启动服务和数据库就全都回来了。3. 核心模块设计与实现细节需求拆完之后我根据实际使用场景把功能切成四个模块灵感板、项目看板、材料库存、作品归档。这四个模块各自独立又通过“项目”这个核心实体串成一条完整的创作链路。下面逐个说设计思路和关键实现。3.1 灵感板收集而不是收藏灵感板的功能表面上很简单就是让你添加图片、链接、文字描述。但我在设计的时候刻意做了一个区分“收藏”是存到角落让它吃灰“收集”是存下来之后还要随时能翻出来刺激自己。所以灵感板不能只是一个静态列表每一条灵感都必须能被关联到一个或多个项目。简单来说我在创建灵感条目的时候会加一个“关联项目”的字段如果不确定具体要挂到哪个项目也可以先放在“未分类”里。后面做项目的时候再回过来把灵感挂过去。这一步设计非常有用因为创作最怕的不是没灵感而是灵感来了之后孤零零地待着没有生根发芽的土壤。我实现的核心模型大致是这样的class Inspiration(db.Model): id db.Column(db.Integer, primary_keyTrue) title db.Column(db.String(200)) image_path db.Column(db.String(255)) link_url db.Column(db.String(500)) note db.Column(db.Text) project_id db.Column(db.Integer, db.ForeignKey(project.id), nullableTrue) created_at db.Column(db.DateTime, defaultdatetime.utcnow)页面模板上我用卡片流的方式展示灵感。每张卡片显示图片或链接标题下面有一行小字标注“已关联项目”或“未分类”。在卡片上直接放两个操作按钮“编辑备注”和“关联项目”。没有多余的信息也没有拖拽排序这些花哨功能。实际用下来越简单的交互越容易坚持使用。3.2 项目看板一条作品的生命周期项目是 artcraft 的核心实体。一个项目对应一个具体作品比如“一把胡桃木书签”、“一幅蓝染挂布”、“一只手工陶杯”。我设计了五个阶段构思、材料准备、制作中、收尾、完成。老实说我在最初版本里用了六七个状态但后来发现状态太多反而让人不知道当前是什么阶段果断收敛成这五个。项目卡片上需要展示的信息包括项目名、封面图、当前状态、开始日期、目标完成日期、最近更新记录。其中“最近更新记录”非常关键它是靠每次记录进度时的时间戳自动反推的。有了这个字段项目列表天然会按活跃度排序正在进行的项目自动排到前面很久没动的项目沉到底部非常符合实际工作习惯。项目状态切换的接口我写得比较简单app.route(/project/int:pid/status, methods[POST]) def update_project_status(pid): project Project.query.get_or_404(pid) new_status request.form.get(status) if new_status in valid_statuses: project.status new_status db.session.commit() record_activity(project.id, 状态变更, f状态更新为: {new_status}) return redirect(url_for(project_detail, pidpid))所有状态切换都会写入活动日志。这个日志模块在后期排查问题的时候帮了我大忙比如某个项目突然看起来不对一查活动记录就能看到是哪天改了状态、传了哪张图。3.3 材料与工具库存名字里就带着数量材料管理模块最让我纠结因为每个人做的东西不一样用到的材料千差万别。有的人是织布用线用量要精确到克有的人是木工需要记录板材尺寸有的人是做首饰材料都是小零件按“个”计数。如果设计成一套固定的字段必然有人不适用。所以我在设计上采用了“通用分类 自定义备注”的方案。每条材料记录包含名称、类别、单位、现有数量、安全库存线和位置。其中“位置”字段是后来才加的起因是我找一卷胶带找了半小时最后发现就在手边工具箱里。自那以后我要求自己做库存时必须填写存放位置。材料的出入库操作我做成一个简单的流水账“入库”操作会新增一条入库记录并增加对应数量“领用”操作会减少对应数量并关联到具体项目这样可以看到每个项目消耗了多少材料当现有数量低于安全库存线时库存列表里会出现醒目标记。这个小功能从一开始的“可有可无”变成了我日常打开频率最高的页面。因为它直接决定了我要不要出门补货也避免了我重复购买那些其实家里还有存货的颜料。3.4 进度记录与作品归档进度记录是使用频率最高的功能。每完成一个小阶段我就会给作品拍一张照片写一两句话。这些记录按时间轴顺序排列构成一个非常直观的制作过程。对创作者来说这个时间轴不仅方便回溯还有另一个作用当你想知道自己“究竟有没有进步”时把几个完整项目的时间轴放在一起看高下立判。实现上进度记录复用了一个统一的“活动记录”机制class Activity(db.Model): id db.Column(db.Integer, primary_keyTrue) project_id db.Column(db.Integer, db.ForeignKey(project.id)) category db.Column(db.String(50)) # note, photo, status content db.Column(db.Text) image_path db.Column(db.String(255)) created_at db.Column(db.DateTime, defaultdatetime.utcnow)作品归档更简单当项目状态变成“完成”后系统会提示补充最终成品图、用料清单配方、工艺总结。这些补充信息平时可不填但一旦填了项目页面就变成了一份可复现的工艺记录。我自己做过一次复刻看着当时留下的参数记录比看图凭记忆乱猜要轻松太多。4. 本地部署与配置实操这一章我给出完整的部署步骤。我的部署环境是 Ubuntu 系统但整个过程在 Debian、Raspberry Pi OS 这类系统上也都适用。为了避免歧义下面所有路径都按/home/www-data/artcraft来算实际部署的时候替换成你自己的目录就好。4.1 环境准备与依赖安装首先确认 Python 版本推荐使用 Python 3.9 以上。然后安装 git 和 pipsudo apt update sudo apt install -y python3 python3-venv python3-pip git nginx mkdir -p /home/www-data cd /home/www-data git clone https://example.com/your-repo/artcraft.git cd artcraft python3 -m venv venv source venv/bin/activate pip install -r requirements.txtrequirements.txt 里的核心依赖并不多我整理下来就这几个Flask3.0.0 Werkzeug3.0.1 gunicorn21.2.0如果是在局域网内自己一个人用gunicorn 也可以不装直接flask run --host0.0.0.0就能跑起来。但如果你打算用 Nginx 做反代并且想让服务在后台持续运行gunicorn 是更规范的选择。4.2 初始化数据库与目录结构依赖装好之后先初始化数据库。我在项目里放了一个init_db.py脚本它会自动完成建表工作source venv/bin/activate python init_db.py初始化完成后项目目录下会出现data文件夹里面包含artcraft.db数据库文件和uploads图片目录。这个data目录是整个项目的核心存档后面做的所有备份都是围绕它来的。接着先生成一把签名密钥我用 openssl 生成随机字符串存放到.env文件里面echo SECRET_KEY$(openssl rand -hex 32) .env这个密钥的作用是给登录会话加密不设置的话每次重启进程用户登录态就会失效。4.3 配置 gunicorn 与开机自启用 gunicorn 启动服务前先确认能正常启动。在 artcraft 目录下执行gunicorn -w 2 -b 127.0.0.1:8000 app:app看到启动日志没有报错之后按下 CtrlC 停止然后把它注册成 systemd 服务。在/etc/systemd/system/artcraft.service里写[Unit] Descriptionartcraft service Afternetwork.target [Service] Userwww-data Groupwww-data WorkingDirectory/home/www-data/artcraft EnvironmentFile/home/www-data/artcraft/.env ExecStart/home/www-data/artcraft/venv/bin/gunicorn -w 2 -b 127.0.0.1:8000 app:app Restartalways [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable artcraft sudo systemctl start artcraft这里有个小提醒Userwww-data是因为后面 Nginx 也要以这个用户读取图片文件同用户能避免一堆权限问题。4.4 Nginx 反向代理配置最后一步是配置 Nginx。在/etc/nginx/sites-available/artcraft里写server { listen 80; server_name your_domain_or_ip; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /uploads/ { alias /home/www-data/artcraft/data/uploads/; } }这里client_max_body_size 20m是必须的Nginx 默认只允许 1MB 的上传请求如果你要传手机拍的照片1MB 是完全不够用的。设置完成之后启用配置并重载sudo ln -s /etc/nginx/sites-available/artcraft /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx部署完成之后浏览器打开服务器地址看到的应该是 artcraft 的登录首页。默认账号是安装过程生成的随机密码第一次登录后建议立刻在设置里替换掉。5. 常见问题与排查技巧实录自托管应用最让人头疼的就是出问题没人帮忙所有坑都得自己填。这里我把运行几个月来实际遇到的几个高发问题整理出来并附上我的排查过程。5.1 图片上传失败因为我在设置里限制了上传大小为 20MB所以超过这个限制的图片直接被 Nginx 拒掉页面报 413 错误。这个属于预期行为不算 bug。真正的问题是为什么明明没超过 20MB 还是上传失败后来排查发现是 gunicorn 的超时设置问题。如果用户上传一张大图中间处理时间超过 gunicorn 默认的 30 秒进程就会强行中断。解决办法是在 systemd 里给 gunicorn 加上超时参数ExecStart/home/www-data/artcraft/venv/bin/gunicorn -w 2 -t 120 -b 127.0.0.1:8000 app:app另外如果你用手机通过局域网访问并上传图片Wi-Fi 信号不好、网络波动也会导致上传中断。这个不属于系统问题但会频繁出现建议在弱网环境里先压缩图片再传。5.2 SQLite 数据库被锁我用 SQLite 的时候已经做好了心理准备但第一次真正碰到database is locked错误时还是愣了一下。原因在于 gunicorn 开了 2 个 worker 进程理论上还是有极小概率出现并发写入冲突特别是在一次请求里同时触发了状态更新和文件重命名。排查之后我做了两件事。第一在 Flask 的数据库连接配置里设置timeout20让微观的锁等待时间更宽松。第二把需要写数据库的高频操作都收敛到同一个请求上下文里减少并发写。设置方法如下import sqlite3 from flask import Flask app Flask(__name__) app.config[SQLALCHEMY_ENGINE_OPTIONS] { connect_args: {timeout: 20} }实际运行下来锁问题从每月偶发一次变成了几乎碰不到。5.3 备份与恢复流程备份做得不够早是我最实际的一条教训。第一版代码写完之后我光顾着测试功能完全忘了备份这回事。后来某次操作失误把数据库表清掉了靠着残存的一份旧备份才把数据找回来从那以后我专门写了一个备份脚本。我目前的备份策略是每天凌晨 3 点跑一次 cron把data目录打包然后同步到另外一台局域网机器上。脚本非常简单只有三行tar -czf /backup/artcraft_$(date \%F).tar.gz /home/www-data/artcraft/data find /backup -name artcraft_*.tar.gz -mtime 14 -delete第一条命令生成压缩包第二条命令自动删除 14 天前的旧备份防止磁盘被撑爆。恢复就更简单了把压缩包解压回去覆盖 data 目录再重启服务就可以。5.4 浏览器缓存导致样式不更新还有一个容易被忽略的问题。前端改版之后服务器已经部署了新文件但浏览器还在用旧缓存页面看起来像没更新一样。这个不算 bug但特别糟心。常规做法是在模板文件或静态文件引用路径后面加版本号。我的做法是在 Jinja2 模板里给 CSS 文件的引用手动加一个时间戳参数link relstylesheet href{{ url_for(static, filenamestyle.css) }}?v{{ version }}然后每次改完前端就给全局变量version加一。这样改完之后浏览器会强制拉取新文件同时不影响常规缓存效率。6. 后续演进方向与个人心得artcraft 做到目前这个程度基本已经让我自己的创作过程顺畅很多。但说实话技术永远是手段这个项目让我最有收获的地方其实是对自己创作习惯的重新梳理。6.1 使用习惯决定工具价值我发现一个特别普遍的现象工具做得再好如果你不持续往里面填充有效信息它就是一堆空表格。反过来哪怕工具稍微简陋一点只要形成了“完成一个阶段就顺手记录一下”的习惯它积累出的数据会很惊人。我个人的建议是不要等到作品完成才一次性补进度记录而是每完成一个小步骤或者遇到想要记住的细节就立即写一句话、拍一张照片。后面回看的时候那些随手记下的碎片反而是最真实也最有价值的部分。另一个我始终坚持的习惯是给每个项目维护“决策记录”。比如某件木工作品我会顺手写一笔“这次没用樱桃木而用了黑胡桃因为客户要求更深的颜色”这种记录在做系列作品时特别管用。它不需要占用多少时间但会让每个项目都留下可以复用的经验。6.2 值得继续扩展的几个方向artcraft 后续还有不少可扩展的点我目前排了几个优先级比较高的标签系统现在“项目—材料—灵感”之间的关联还不够灵活加上标签之后可以做更细致的检索统计视图统计每个材料的使用趋势对成本控制很有帮助多用户支持后面如果要给工作室团队用就需要加入用户权限体系这也是目前代码架构限制比较大的地方二维码标签打印给存放材料的箱子打印带二维码的标签手机扫码就能看到这个位置放了什么东西这个想法我很想实现。扩展方向是无限的但核心原则不变保持简单、保持数据可控、保持作者本人能长期维护。这三点做到了工具自然会越用越顺手。如果你也想折腾类似的自托管创作工具希望这篇复盘能给你一些参考。去写代码之前先花点时间想清楚自己的工作流这个时间投入绝对值得。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
