Star Office UI部署教程：用Docker+Nginx打造像素风AI办公室

1. 项目概述AI龙虾的像素办公室是什么为什么值得部署第一次听到“给你的AI龙虾打造一间像素办公室”这个说法估计不少人会有点懵。什么是AI龙虾像素办公室又是干嘛的先拆开说。“AI龙虾”其实是圈内对自托管AI助手服务的一个戏称。很多开发者在折腾本地部署大模型的时候会起一些可爱的代号比如把正在运行AI服务的机器叫“龙虾主机”把喂给模型的外部知识库叫“龙虾饲料”。“龙虾”这个名字怎么来的已经不可考但越来越多人在自建AI服务时默认用它指代自己的AI实例。而“像素办公室”指的是基于 Star Office UI 搭建的Web界面——一个风格复古、带强烈像素游戏味道的办公型前端面板用来管理你的AI助手、对话记录、知识库文件、团队协作入口。Star Office UI 本身是个开源项目整个界面走的是像素风和复古办公桌面风图标是16bit风格窗口可以在浏览器里拖动、缩放、叠加非常有当年Windows 98的味道但底层跑的又是现代Web技术。它能解决的问题也很直接当你把大模型部署在服务器上不管是DeepSeek、Qwen还是GLM系列通常只有一个纯API接口或者极简的Web对话页面要让它真正被团队日常使用缺一个好看、好用的前端壳。Star Office UI 就是干这个的——把AI能力包装成一个像素风格的在线办公室成员登录之后就像打开一个复古桌面在上面和AI对话、查看任务看板、丢文件进去做RAG检索体验完全不一样。这篇教程要做的就是把 Star Office UI 从零部署到自己的服务器上然后配置公网访问让团队成员随时随地通过浏览器进入这间“办公室”不在内网也能用。整条流程覆盖环境准备、Docker部署、配置文件修改、公网方案选型、HTTPS证书、常见故障排查内容是按我实际踩坑的顺序写的适合有一定Linux基础、但对前端部署和网络配置还不算熟悉的开发者参考。我自己在部署的时候最大的感受是Star Office UI 本身不难装真正折腾人的是公网访问那一环——域名解析、反向代理、证书续期、防火墙策略每一样都藏着小坑。这篇文章会把每一步的思考逻辑和实操命令全部摊开让你不光能照着做还能理解为什么要这么做。2. 整体设计与技术选型为什么选Docker部署为什么需要公网访问2.1 Docker部署的优势以及本地环境要求Star Office UI 支持多种部署方式官方提供了源码构建、二进制发布包和Docker镜像三种路径。我强烈建议直接用Docker原因很现实这项目的前端构建依赖Node.js版本很挑源码编译时候我遇到过Node 18和Node 20下依赖锁文件冲突的问题二进制包又需要自己处理运行环境变量而Docker镜像把运行时、依赖、配置文件全部封装好了拉下来就能跑。从运维角度看Docker容器化的好处更明显。Star Office UI 需要和一个向量数据库默认支持Chroma或Qdrant配合才能做知识库功能如果直接装裸机你得手动装Python环境、装数据库、配端口稍有不慎就会污染系统环境。但用Docker Compose编排一条命令把UI、数据库、Redis缓存三个服务全部拉起升级的时候也只要拉新镜像重建容器不碰宿主机安全省事。服务器配置方面Star Office UI 本身对资源消耗并不高。由于推理能力来自后端的大模型服务Star Office UI 只是一个前端界面层加数据库层实测下来2核4G内存的云服务器就能流畅跑起来。如果还想在同一台机器上部署一个量化过的7B模型那建议至少4核8G内存并且要带GPU否则对话响应会很慢。磁盘方面镜像本体加依赖大概占2G左右知识库文件就看你实际存多少了预留20G比较稳妥。2.2 公网访问的整体思路与安全考量公网访问是本教程的重头戏。为什么非要公网因为本地部署的AI服务默认只监听127.0.0.1或者内网IP只有局域网内能访问。如果办公室里的人想在家用、出差路上用或者你部署在一台家用NAS上想让异地朋友一起用就必须把服务暴露到公网。这里要强调一个重要认知对于需要登录的Web服务公网暴露不等于裸奔。Star Office UI 自带会话认证机制默认会要求创建管理员账号所有请求都要带token才能过。但只靠应用层认证还不够稳妥我在部署实践中总结出一个安全组合供参考应用层开启强密码策略关闭默认注册入口。在Nginx反向代理层启用HTTPS用Let‘s Encrypt免费证书。在防火墙层面限制端口来源只放行80/443端口其他管理端口一律不对外开放。如果服务器上还跑着SSH建议改掉默认22端口或者限制SSH只允许特定IP连接。公网访问方案有几种下面这个表格是我整理的一个对比方便你根据实际场景选型方案类型适用场景优点缺点云服务器公网IP 域名解析有自己的云主机带宽充足访问稳定可配置HTTPS性能可控需要备案大陆机房域名要花钱内网穿透工具如frp、cpolar服务跑在家里NAS或旧电脑上无需公网IP搭建快依赖中转服务器延迟较高Cloudflare Tunnel有域名且愿意走Cloudflare无需开放入站端口自带WAF防护国内访问Cloudflare线路不稳定反向代理Nginx Let‘s Encrypt自己掌握域名和服务器安全可控支持证书自动续期需要一定的Nginx配置经验我自己的选择是“云服务器公网IP Nginx反向代理 域名HTTPS”这也是本篇教程的主线。这样做的好处是链路完全可控遇到问题可以逐层排查而且Nginx配置一次之后以后在这台服务器上再部署别的Web服务改个配置文件就能复用同样套路。3. 环境准备与Star Office UI部署实操3.1 服务器基础环境初始化部署之前先把基础环境准备好我用的是Ubuntu 22.04 LTS这个系统兼容性最好下面所有命令都基于它来写。登录服务器后第一步是更新系统包和安装必备工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git vim ufw docker.io docker-compose-pluginDocker在Ubuntu仓库里直接带没必要走官方源那一套花活。装好之后确认一下版本docker --version docker compose version注意Ubuntu 22.04仓库里的docker-compose-plugin对应的是docker compose命令中间有空格不是老版的docker-compose带横杠。如果你在旧教程里看到的是带横杠的写法要么是本机装了旧版要么是教程过时了用docker compose是对的。接着把当前用户加入docker组这样不用sudo也能执行docker命令重新登录生效sudo usermod -aG docker $USER newgrp docker启动防火墙把SSH端口放行这里假设SSH是22端口。如果你已经改成其他端口记得改成实际端口sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable为什么要先把80和443放行因为后面Nginx要监听这两个端口对外提供HTTP/HTTPS服务。如果先启防火墙再开端口部署完发现外部访问不了很容易怀疑是应用出了问题实际上是被防火墙拦了这一步先做能省后面大量的排查时间。3.2 获取Star Office UI的Docker部署文件Star Office UI的部署文件在GitHub仓库里已经打好了包直接克隆到服务器mkdir -p /opt/star-office cd /opt/star-office git clone https://github.com/star-office/star-office-ui.git .这里注意两点。第一仓库里通常包含docker-compose.yml和.env.example文件前者定义了服务编排后者是环境变量模板。第二不要直接用.env.example这个名字作为配置文件需要复制一份cp .env.example .env vi .env编辑.env文件是部署过程中最关键的一步。里面有几个必改项下面这个表格说明了每项的作用和建议值配置项作用建议值APP_URL应用的对外访问地址影响CORS和OAuth回调https://office.yourdomain.comADMIN_EMAIL管理员邮箱首次初始化用它创建账号你的真实邮箱ADMIN_PASSWORD管理员密码至少12位包含大小写和数字生成一串强密码不要用弱口令DB_CONNECTION数据库类型mysql或pgsql取决于compose里配的库VECTOR_STORE知识库向量数据库chroma默认无需改JWT_SECRET用于签发登录token的密钥用openssl rand -hex 32生成JWT_SECRET这个一定要自己重新生成用仓库里默认的值是不安全的。命令openssl rand -hex 32把生成结果粘到.env文件里。3.3 一键启动Docker Compose拉起全套服务配置文件改好之后直接启动docker compose up -d第一次启动会拉取镜像Star Office UI的主镜像大约几百兆加上MySQL和Redis镜像总下载量在1.5G左右具体看网络情况。拉完之后容器起来用下面的命令看状态docker compose ps正常情况下会有三个容器处于Up状态appStar Office UI主应用、dbMySQL或PostgreSQL、redis缓存服务。如果有容器启动失败用docker compose logs看具体报错。启动完成后在服务器本地做一个快速验证——用curl请求应用首页看看HTTP状态码是不是200curl -I http://localhost:8080如果返回正常的200响应说明应用本体工作正常。此时还不急着配公网先用SSH端口转发把界面拉出来看一眼也是可以的但更推荐直接跳到下一步配置Nginx。因为只改了.env里的APP_URL如果直接用IP和端口访问前端的静态资源路径可能会错乱导致页面白屏。所以先把反向代理配好再用完整域名访问才是正确的顺序。4. 让办公室公网可见Nginx反向代理与HTTPS证书配置4.1 域名解析与Nginx安装Star Office UI跑起来只是第一步接下来要把它通过一个标准的域名暴露到公网。首先要有一个域名并且把解析记录指向你的云服务器公网IP。假设你的域名是yourdomain.com给办公室子域添加一条A记录主机记录填office记录值填服务器IP。解析生效一般需要几分钟到几十分钟不等用ping命令能确认解析是否生效ping office.yourdomain.com解析通了之后安装Nginx。Ubuntu下很简单sudo apt install -y nginxNginx装好后默认站点配置文件在/etc/nginx/sites-available/default但我们不用默认站点新建一个独立的配置文件方便维护sudo vi /etc/nginx/sites-available/star-office配置文件内容如下注意适配你自己的域名server { listen 80; server_name office.yourdomain.com; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2)$ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; expires 7d; } }这段配置里有两个细节要解释。第一client_max_body_size 50m是放宽上传文件大小限制如果你要用Star Office UI的知识库功能传PDF或Word文档默认的1m上传限制会导致文件传不上去这个坑我帮你们提前填了。第二proxy_set_header X-Forwarded-Proto $scheme这行很关键它告诉后端真实请求协议如果漏掉后面配HTTPS时应用内可能会出现重定向循环。把配置启用sudo ln -s /etc/nginx/sites-available/star-office /etc/nginx/sites-enabled/ sudo rm /etc/nginx/sites-enabled/default sudo nginx -t sudo systemctl reload nginx此时用http://office.yourdomain.com应该能访问到Star Office UI的登录页了。不过HTTP明文传输意味着账号密码是裸奔的所以接下来必须上HTTPS。4.2 Let‘s Encrypt免费证书申请与自动续期HTTPS证书我推荐用Let’s Encrypt免费、主流浏览器都信任、自动续期方便。安装certbot工具sudo apt install -y certbot python3-certbot-nginx然后一条命令申请证书并自动修改Nginx配置sudo certbot --nginx -d office.yourdomain.comcertbot会自动验证域名所有权它会短暂修改Nginx配置来响应ACME挑战成功后会问你要不要强制跳转HTTPS选2redirect。证书申请成功后certbot会自动修改Nginx配置加入SSL证书路径和80端口跳转443的规则。证书有效期是90天需要定期续期。certbot已经内置了续期定时器手动验证一下就行sudo certbot renew --dry-run返回Congratulations之类的提示就说明自动续期机制已正常启用。这一步做完再访问https://office.yourdomain.com浏览器地址栏会出现绿色小锁数据全程加密可以放心开始使用了。4.3 防火墙与其他服务的端口安全策略域名和HTTPS都搞定之后再回头看一遍服务器安全策略。首先确认Nginx监听的是80和443端口而Star Office UI的应用端口8080只是在Nginx内部使用的不应该暴露到公网。执行下面这行命令检查一下8080端口是否被防火墙拦着sudo ufw status numbered如果看到8080端口是ALLOW状态把它删掉sudo ufw delete allow 8080/tcp为什么要这么谨慎因为很多攻击者的扫描脚本会扫非常见端口如果Star Office UI的原始端口暴露虽然它有登录认证但应用层若有未知漏洞就会成为突破口。让所有外部流量都经过Nginx这一层相当于只留两个“门”——80和443其他端口一律封死攻击面大幅缩小。另外如果你打算在这台服务器上继续部署其他AI相关服务比如后面接一个本地大模型API建议把API服务的端口也绑定在内网或仅允许本机访问不要让它们直接暴露公网。比如你用vLLM跑了一个独立的推理服务默认监听8000端口可以用Nginx按路径转发到/v1/或做一层API Key校验总之不要裸奔。5. 进入办公室初始化配置、AI后端对接与个性化设置5.1 首次登录与管理员账号初始化浏览器打开https://office.yourdomain.com首次访问会进入初始化向导。这里要用到前面在.env里填写的邮箱和密码或者根据页面提示创建一个新的管理员账号。初始化过程会要求设置站点名称可以取个“XX工作室AI办公室”之类的名字。默认语言Star Office UI支持中文界面切换之后像素风里出现汉字也别有一番味道。是否开启团队注册如果是私人使用必须关掉如果公司内部用也可以关掉由管理员统一创建账号。初始化完成后进入主界面就是那个熟悉的“像素桌面”——底部是任务栏桌面上有几个图标包括“AI对话”“知识库”“文件中心”“系统设置”等。整个界面风格非常像我小时候玩过的RPG游戏菜单用起来却没有花哨的违和感各个窗口都可以拖拽缩放多任务操作时反而比传统后台面板顺手。5.2 对接本地或云端大模型推理服务Star Office UI本质上是一个前端真正回答问题的能力来自背后的大模型。这个对接步骤很容易被忽略很多人部署完发现AI不回复其实就是后端没配。进入“系统设置”找到“模型管理”或“AI Provider”配置项。在配置里填三个关键信息API Base URL指向你的推理服务地址。如果大模型就部署在同一台服务器上填http://127.0.0.1:8000/v1即可如果在另一台机器填内网IP或域名。API Key如果推理服务有鉴权填对应的Key如果用的是本地vLLM或Ollama且没开鉴权可以随便填一个占位符但建议还是开一下。模型名称填实际部署的模型名比如qwen2.5-7b-instruct或者deepseek-r1-distill-qwen-14b。这个必须和推理服务里注册的名字完全一致否则会报模型不存在。填完之后点测试连接看到返回成功就说明已接通。对话窗口随便发一句“你好”如果收到了像素对话框里蹦出来的回复整个链路就跑通了。5.3 个性化像素主题与常用功能调整Star Office UI 的像素主题支持自定义如果默认的蓝白色调看腻了可以在“外观设置”里换颜色主题。这个项目内置了多套配色方案有经典灰色、复古绿色、暗黑紫色等我试了一圈之后发现暗黑紫最耐看窗口阴影和像素描边在暗色下更有质感。还有一个很实用的功能是“快捷工具”类似Windows桌面的快捷方式可以把常用的对话场景做成桌面图标。比如说你建了一个“产品文案助手”的对话机器人绑定了一个固定角色提示词然后把它发送到桌面以后直接双击这个图标就进入对应的对话窗口不用每次重新选模型、写提示词。这个功能对团队效率提升极其明显我把常用的几个业务场景——周报润色、代码审查、会议纪要结构化——都建成了桌面快捷方式同事用起来像在用一套定制的AI工作台。6. 常见问题与故障排查实录6.1 部署与访问环节的典型报错把我在部署过程中以及帮朋友排查时遇到的典型问题整理成了一张表供参考现象可能原因解决方法docker compose up拉取镜像超时网络原因或镜像仓库慢配置镜像加速器或重试几次有个别镜像体积大耐心等容器启动后自动退出.env配置项缺失或数据库连接失败docker compose logs看日志检查DB密码和DB_HOST是否匹配页面能打开但CSS错乱、图标不显示反向代理WebSocket或静态资源路径配置问题确认Nginx配置中的proxy_set_header Host已设置刷新浏览器缓存登录后跳转回登录页循环APP_URL没有写成HTTPS域名重新检查.env里的APP_URL改为https://office.yourdomain.com并重启容器HTTPS证书申请失败域名解析未生效或80端口未放行先确认ping通再确认防火墙放行最后重试certbot对话接口返回401API Key未填或填错到模型管理里重新填写正确的Key并测试连接上传文件失败提示413Nginx上传大小限制在Nginx配置文件里加client_max_body_size并reload最容易被忽略的一种情况是改了.env之后没有重建容器只是重启容器导致新配置不生效。正确做法是docker compose down docker compose up -d因为.env是在容器创建时读取的仅restart不会刷新环境变量。6.2 数据库持久化与备份策略Star Office UI的数据存在MySQL里包括用户账号、对话记录、知识库索引。Docker容器如果被误删数据会跟着没除非你把数据目录挂载到宿主机。好在官方Compose文件默认已经做了数据卷挂载你可以通过下面命令确认docker volume ls docker volume inspect star-office_db_data为了安全建议再做一层定时备份。写一个简单的cron任务每天凌晨把数据库导出为SQL文件保留最近7天sudo crontab -e加入一行0 2 * * * docker exec star-office-db-1 mysqldump -u root -p你的密码 star_office /backup/star_office_$(date \%F).sql find /backup -name star_office_* -mtime 7 -delete注意两点第一star-office-db-1换成你实际容器名用docker ps查看第二数据库名以实际为准。备份这事看着不起眼一旦服务器磁盘损坏或者误操作删了库就知道这份备份值多少钱了。我在本地环境还遇到过一次MySQL容器内存占用过高被杀掉的情况后来通过给compose文件的MySQL服务加了一行mem_limit: 1g限制内存上限才稳定下来。6.3 性能调优与资源占用控制Star Office UI 跑起来之后在我那台2核4G的云服务器上实际内存占用约1.5G左右App 800M MySQL 500M Redis 150MCPU平时几乎不动。如果同一台机器还要跑大模型推理资源就紧张了对话并发一高整体响应会明显变慢。我的建议是如果条件允许把Star Office UI和大模型推理服务分开部署在两台机器上。UI服务器只要低配即可推理服务器上GPU才是核心。两边通过内网API互通互不抢占资源排查问题也更清晰。如果只能部署在一台机器上可以考虑给PHP-FPM或Java进程做内存限制Star Office UI的容器是PHPOctane架构具体看Compose文件并关闭不需要的AI服务来释放内存。另外把MySQL的innodb_buffer_pool_size调低到256M之类能省出不少内存。改这个参数需要编辑MySQL容器里的配置文件或者在Compose文件中通过command参数覆盖操作起来略麻烦但对小内存服务器来说是实打实有效的。7. 更多场景玩法从单机部署到团队协作Star Office UI除了最基础的AI对话功能之外还有不少值得挖掘的玩法。这里说几个我自己实际用过的方向你可以根据自己的情况扩展。第一个方向是把它做成团队的“AI工作台桌面”。不只是和AI对话还可以在办公室里挂上团队成员共享的知识库——所有上传到知识库的文档会被向量化之后任何成员在对话时都可以引用这些文档来回答问题。对于一个10人以内的小团队这基本就是一套轻量级的私有RAG系统不用再额外去订阅各种在线知识库服务。第二个方向是用它的“流程自动化”能力。Star Office UI内置了一个简单的定时任务机制可以设置每天晚上自动对某个文件夹下的文档做向量化更新第二天成员提问时知识库数据就是最新的。还有Webhook入口可以对接GitLab提交事件或客服工单系统让AI在新任务生成时自动提炼要点并推送到会话窗口。第三个方向是像素主题的深度自定义。Star Office UI的主题文件是CSS变量驱动的在“外观设置”的高级模式里可以直接注入自定义CSS。你可以把办公室的桌面壁纸替换成自己设计的像素图或者修改图标文件让整个界面更符合自己公司的品牌调性。我花了半天时间把图标换成了几个同事画的像素小人据说团队幸福感提升明显。这些玩法都不需要改代码都是在管理界面里点一点、传一传就能实现的但效果却能让这个自建工具真正贴合团队的使用习惯。8. 写在最后的部署经验与建议回头再看整个部署过程Star Office UI本身并不复杂Docker Compose拉起来、改个环境变量半小时内就能跑通内网访问。真正决定这个项目能不能稳定用起来的反而是那些看起来不那么“酷”的环节——域名解析是否设置好、证书能不能自动续期、数据库有没有定时备份、公网端口暴露是否克制。我个人在实际操作中的体会是像素办公室这个项目最打动人的地方不在于它有多强的AI能力而在于它把冷冰冰的部署产物包装成了一个有温度的“空间”。当团队成员第一次在浏览器里看到那个像素桌面发现快捷方式上写着“代码审查助手”“周报润色小站”时那种惊喜感是纯API接口永远给不了的。最后再分享一个小技巧如果多人同时使用建议在系统设置里打开“会话隔离”选项让每个成员的对话记录互相独立。我最初部署后所有的对话都混在一起后来才发现有这个开关开启后每个人的对话历史隔离开既保护了隐私又避免了误看别人内容的尴尬。按照这次部署的经验把Star Office UI跑起来只是开始真正让自己满意的是后续的持续调优和场景定制。像素办公室的桌面可以越用越顺手希望这份教程也能帮你少走几步弯路。